1FAQ(1) User Contributed Perl Documentation FAQ(1)
2
6 PDL::FAQ - Frequently asked questions about PDL
7
9 Current FAQ version: 0.7
10
12 This is version 0.7 of the PDL FAQ, a collection of frequently asked
13 questions about PDL - the Perl Data Language.
14
16 Q: 1.1 Where to find this document
17 You can find the latest version of this document at http://pdl.source‐
19 forge.net/FAQ .
20 Q: 1.2 How to contribute to this document
22 This is a considerably reworked version of the PDL FAQ. As such many
24 errors might have crept in and many updates might not have made it in.
25 You are explicitly encouraged to let us know about questions which you
26 think should be answered in this document but currently aren't. Simi‐
27 larly, if you think parts of this document are unclear, please tell the
28 FAQ maintainer about it. Where a specific answer is taken in full from
29 someone's posting the authorship should be indicated, let the FAQ main‐
30 tainer know if it isn't. For more general information explicit acknowl‐
31 edgement is not made in the text, but rather there is an incomplete
32 list of contributors at the end of this docuement. Please contact the
33 FAQ maintainer if you feel hard done by.
34 Send your comments, additions, suggestions or corrections to the PDL
36 mailing list at perldl@jach.hawaii.edu. See below for instructions on
37 how to join the mailing lists.
38
40 Q: 2.1 What is PDL ?
41 PDL stands for Perl Data Language . To say it with the words of Karl
43 Glazebrook, initiator of the PDL project:
44 The PDL concept is to give standard perl5 the ability
46 to COMPACTLY store and SPEEDILY manipulate the large
47 N-dimensional data sets which are the bread and butter
48 of scientific computing. e.g. $a=$b+$c can add two
49 2048x2048 images in only a fraction of a second.
50 It provides tons of useful functionality for scientific and numeric
52 analysis.
53 For readers familiar with other scientific data evaluation packages it
55 may be helpful to add that PDL is in many respects similar to IDL, MAT‐
56 LAB and similar packages. However, it tries to improve on a number of
57 issues which were perceived (by the authors of PDL) as shortcomings of
58 those existing packages.
59 Q: 2.2 Who supports PDL? Who develops it?
61 PDL is supported by its users. General informal support for PDL is pro‐
63 vided through the PDL mailing list (perldl@jach.hawaii.edu , see
64 below).
65 As a Perl extension (see below) it is devoted to the idea of free and
67 open development put forth by the Perl community. PDL was and is being
68 actively developed by a loosely knit group of people around the world
69 who coordinate their activities through the PDL development mailing
70 list (pdl-porters@jach.hawaii.edu , see below). If you would like to
71 join in the ongoing efforts to improve PDL please join this list.
72 Q: 2.3 Why yet another Data Language ?
74 There are actually several reasons and everyone should decide for him‐
76 self which are the most important ones:
77 · PDL is "free software". The authors of PDL think that this concept
79 has several advantages: everyone has access to the sources -> bet‐
80 ter debugging, easily adaptable to your own needs, extensible for
81 your purposes, etc... In comparison with commercial packages such
82 as Matlab and IDL this is of considerable importance for workers
83 who want to do some work at home and cannot afford the considerable
84 cost to buy commercial packages for personal use.
85 · PDL is based on a powerful and well designed scripting language:
87 Perl. In contrast to other scientific/numeric data analysis lan‐
88 guages it has been designed using the features of a proven language
89 instead of having grown into existence from scratch. Defining the
90 control structures while features were added during development
91 leads to languages that often appear clumsy and badly planned for
92 most existing packages with similar scope as PDL.
93 · Using Perl as the basis a PDL programmer has all the powerful fea‐
95 tures of Perl at his hand, right from the start. This includes reg‐
96 ular expressions, associative arrays (hashes), well designed inter‐
97 faces to the operating system, network, etc. Experience has shown
98 that even in mainly numerically oriented programming it is often
99 extremely handy if you have easy access to powerful semi-numerical
100 or completely non-numerical functionality as well. For example, you
101 might want to offer the results of a complicated computation as a
102 server process to other processes on the network, perhaps directly
103 accepting input from other processes on the network. Using Perl and
104 existing Perl extension packages things like this are no problem at
105 all (and it all will fit into your "PDL script").
106 · Extremely easy extensibility and interoperability as PDL is a Perl
108 extension; development support for Perl extensions is an integral
109 part of Perl and there are already numerous extensions to standard
110 Perl freely available on the network.
111 · Integral language features of Perl (regular expressions, hashes,
113 object modules) immensely facilitated development and implementa‐
114 tion of key concepts of PDL. One of the most striking examples for
115 this point is probably PDL::PP (see below), a code genera‐
116 tor/parser/pre-processor that generates PDL functions from concise
117 descriptions.
118 · None of the existing DLs follow the Perl language rules, which the
120 authors firmly believe in:
121 · TIMTOWTDI: There is more than one way to do it. Minimalist
123 languages are interesting for computer scientists, but for
124 users, a little bit of redundancy makes things wildly easier to
125 cope with and allows individual programming styles - just as
126 people speak in different ways. For many people this will
127 undoubtedly be a reason to avoid PDL ;)
128 · Simple things are simple, complicated things possible: Things
130 that are often done should be easy to do in the language,
131 whereas seldom done things shouldn't be too cumbersome.
132 All existing languages violate at least one of these rules.
134 · As a project for the future PDL should be able to use super com‐
136 puter features, e.g. vector capabilities/parallel processing. This
137 will probably be achieved by having PDL::PP (see below) generate
138 appropriate code on such architectures to exploit these features.
139 · [ fill in your personal 111 favourite reasons here...]
141 Q: 2.4 What is PDL good for ?
143 Just in case you do not yet know what the main features of PDL are and
145 what one could do with them, here is a (necessarily selective) list of
146 key features:
147 PDL is well suited for matrix computations, general handling of multi‐
149 dimensional data, image processing, general scientific computation,
150 numerical applications. It supports I/O for many popular image and data
151 formats, 1D (line plots), 2D (images) and 3D (volume visualisation,
152 surface plots via OpenGL - for instance impelmented using Mesa), graph‐
153 ics display capabilities and implements lots of numerical and semi-
154 numerical algorithms.
155 Through the powerful pre-processor it is also easy to interface Perl to
157 your favourite C routines, more of that further below.
158 Q: 2.5 What is the connection between PDL and Perl ?
160 PDL is a Perl5 extension package. As such it needs an existing Perl5
162 installation (see below) to run. Furthermore, much of PDL is written in
163 perl (+ some core functionality that is written in C). PDL programs are
164 (syntactically) just perl scripts that happen to use some of the func‐
165 tionality implemented by the package "PDL".
166 Q: 2.6 What do I need to run PDL on my machine ?
168 Since PDL is just a Perl package you need first of all an installation
170 of Perl on your machine. As of this writing PDL requires version 5.6 of
171 Perl, version 5.8 or higher is strongly recommended. More information
172 on where and how to get a Perl installation can be found at the Perl
173 home page http://www.perl.org and at many CPAN sites (if you do not
174 know what CPAN is check the answer to the next question).
175 To build PDL you also need a working C compiler and support for Xsubs
177 the package Extutils::MakeMaker. See also
178 http://pdl.perl.org/ports.html for a list of machines where PDL has
179 been tested. If you don't have a compiler there might be a binary dis‐
180 tribution availabe, see "Binary distributions" below.
181 If you can (or cannot) get PDL working on a new (previously unsup‐
183 ported) platform we would like to hear about it. Please, report your
184 success/failure to the PDL mailing list at perldl@jach.hawaii.edu . We
185 will do our best to assist you in porting PDL to a new system.
186 Q: 2.7 Where do I get it?
188 PDL is available as source distribution in the Comprehensive Perl Ar‐
190 chive Network , or CPAN. This archive contains not only the PDL dis‐
191 tribution but also just about everything else that is Perl-related.
192 CPAN is mirrored by dozens of sites all over the world. The main site
193 is http://www.cpan.org , and local CPAN sites (mirrors) can be found
194 there. Within CPAN you find the latest released version of PDL in the
195 directory /modules/by-module/PDL/. PDLs homepage is at
196 http://pdl.perl.org and the latest version can also be downloaded from
197 there.
198 Q: 2.8 What do I have to pay to get PDL?
200 We are delighted to be able to give you the nicest possible answer on a
202 question like this: PDL is *free software* and all sources are publicly
203 available. But still, there are some copyrights to comply with. So
204 please, try to be as nice as we (the PDL authors) are and try to comply
205 with them.
206 Oh, before you think it is *completely* free: you have to invest some
208 time to pull the distribution from the net, compile and install it and
209 (maybe) read the manuals.
210
212 Q: 3.1 Where can I get information on PDL?
213 The complete PDL documentation is available with the PDL distribution.
215 If you have PDL installed on your machine and are on a unix like system
216 then you can read the PDL manuals with the " man" command. " man PDL"
217 get you started, " man PDL::FAQ" will let you read this document, etc.
218 In any case (i.e. also on non-unixes) " perldoc PDL::Intro" should
219 work, and if you don't want to type that much, " pdldoc intro" should
220 also work.
221 The easiest way by far, however, to get familiar with PDL is to use the
223 PDL online help facility from within the " perldl" shell. Just type "
224 perldl" at your system prompt. Once you are inside the " perldl" shell
225 type " help" . Using the " help" and " apropos" commands inside the
226 shell you should be able to find the way round the documentation. Even
227 better, you can immediately try your newly acquired knowledge about PDL
228 by issuing PDL/perl commands directly at the command line. To illus‐
229 trate this process, here is the record of a typical perldl session of a
230 PDL beginner (lengthy output is only symbolically reproduced in braces
231 ( <... ...> ) ):
232 unix> perldl
234 perldl> help
235 <.... help output ....>
236 perldl> help PDL::Impatient
237 <.... man page ....>
238 perldl> $a = pdl (1,5,7.3,1.0)
239 perldl> $b = sequence float, 4, 4
240 perldl> help inner
241 <.... help on the 'inner' function ....>
242 perldl> $c = inner $a, $b
243 perldl> p $c
244 [22.6 79.8 137 194.2]
245 For further sources of information that are accessible through the
247 internet see next question.
248 Q: 3.2 Are there other PDL information sources on the internet?
250 First of all, for all purely Perl-related questions there are tons of
252 sources on the net. Good points to start are http://www.perl.com and
253 http://www.perl.org .
254 The PDL home site can be accessed by pointing your web browser to
256 http://pdl.perl.org . It has tons of goodies for anyone interested in
257 PDL:
258 · PDL distributions
260 · Online documentation
262 · Pointers to an HTML archive of the PDL mailing lists
264 · A list of platforms on which PDL has been successfully tested.
266 · News about recently added features, ported libraries, etc.
268 · Name of the current pumpkin holders for the different PDL modules
270 (if you want to know what that means you better had a look at the
271 web pages).
272 If you are interested in PDL in general you can join the PDL mailing
274 list perldl@jach.hawaii.edu. This is a forum to discuss programming
275 issues in PDL, report bugs, seek assistance with PDL related problems,
276 etc. To subscribe, send a message to perldl-request@jach.hawaii.edu
277 containing a string in the following format:
278 subscribe me@my.email.address
280 where you should replace the string " me@my.email.address" with your
282 email address. A searchable archive and a hypertext version of the
283 traffic on this list (1997-2004) can be found at
284 http://www.xray.mpe.mpg.de/mailing-lists/perldl/ . More recent messages
285 (since June 2005) can be found at http://mailman.jach.hawaii.edu/mail‐
286 man/listinfo/perldl
287 If you are interested in all the technical details of the ongoing PDL
289 development you can join the PDL developers mailing list
290 pdl-porters@jach.hawaii.edu . To subscribe, send a message to
291 pdl-porters-request@jach.hawaii.edu containing a string in the follow‐
292 ing format:
293 subscribe me@my.email.address
295 where you should replace the string " me@my.email.address" with your
297 email address. A searchable archive and a hypertext version of the
298 traffic on this list (1997-2004) can be found at
299 http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/ . More recent
300 messages (since June 2005) can be found at http://mail‐
301 man.jach.hawaii.edu/mailman/listinfo/pdl-porters
302 Crossposting between these lists should be avoided unless there is a
304 very good reason for doing that.
305 Q: 3.3 What is the current version of PDL ?
307 As of this writing (FAQ version 0.7 of April 2006) version 2.4.3 is
309 nearing release. The latest stable version should always be available
310 from a CPAN mirror site near you (see Question 2.7 for info on where to
311 get PDL.
312 The most current (possibly unstable) version of PDL can be obtained
314 from the CVS repository, see Question 4.8
315 Q: 3.4 I want to contribute to the further development of PDL. How
317 can I help?
318 If you have a certain project in mind you should check if somebody else
320 is already working on it or if you could benefit from existing modules.
321 Do so by posting your planned project to the PDL developers mailing
322 list at pdl-porters@jach.hawaii.edu . See the subscription instructions
323 in Question 3.2. We are always looking for people to write code and/or
324 documentation ;).
325 Q: 3.5 I think I have found a bug in the current version of PDL.
327 What shall I do?
328 First, make sure that the bug/problem you came across has not already
330 been dealt with somewhere else in this FAQ. Secondly, you can check the
331 searchable archive of the PDL mailing list to find whether this bug has
332 already been discussed. If you still haven't found any explanations you
333 can post a bug report to perldl@jach.hawaii.edu , or through the Bugs
334 link on http://pdl.perl.org .
335
337 Q: 4.1 I have problems installing PDL. What shall I do?
338 First make sure you have read the file INSTALL in the distribution.
340 This contains a list of common problems which are unnecessary to repeat
341 here. Next, check the file perldl.conf to see if by editing the config‐
342 uration options in that file you will be able to successfully build
343 PDL. Some of the modules need additional software installed, please
344 refer to the file DEPENDENCIES for further details. Make sure to edit
345 the location of these packages in perldl.conf if you have them in non-
346 standard locations.
347 If you would like to save an edited perldl.conf for future builds just
349 copy it as ~/.perldl.conf into your home directory where it will be
350 picked up automatically during the PDL build process.
351 If you still can't make it work properly please submit a bug report
353 including detailed information on the problems you encountered to the
354 perldl mailing list ( perldl@jach.hawaii.edu , see also above).
355 Response is often rapid.
356 Q: 4.2 Are there configuration files for PDL I have to edit?
358 Most users should not have to edit any configuration files manually.
360 However, in some cases you might have to supply some information about
361 akwardly placed include files/libraries or you might want to explicitly
362 disable building some of the optional PDL modules. Check the files
363 INSTALL and perldl.conf for details.
364 If you had to manually edit perldl.conf and are happy with the results
366 you can keep the file handy for future reference. Place it in
367 ~/.perldl.conf where it will be picked up automatically or use " perl
368 Makefile.PL PDLCONF=your_file_name" next time you build PDL.
369 Q: 4.3 Do I need other software for successfull operation?
371 For the basic PDL functionality you don't need any additional software.
373 However, some of the optional PDL modules included in the distribution
374 (notably most graphics and some I/O modules) require certain other
375 libraries/programs to be installed. Check the file DEPENDENCIES in the
376 distribution for details and directions on how to get these.
377 Q: 4.4 PDL compilation ends with " Error: PL_na not declared" or
379 similar
380 You have probably upgraded perl to 5.6 and tried to recompile an old
382 version of PDL. The solution to this problem is to upgrade to a version
383 (>2.005) which should have this fixed.
384 If the latest version of PDL does not fix this problem for you, and you
386 have made sure your old installation is not interfering, you should
387 post a message to the mailing-list.
388
390 Q: 4.5 What binary distributions are available?
391 Information about binary distributions of PDL can be found on
393 http://pdl.perl.org . At present there are binary distributions of PDL
394 for Linux (RedHat and Debian), FreeBSD and Windows, though they might
395 not be the most recent version. If someone is interested in providing
396 binary distributions for other architectures, that would be very wel‐
397 come. Let us know on the pdl-porters@jach.hawaii.edu mailing list. Also
398 check your Linux distibution's package manager as many now include PDL.
399 Q: 4.6 Does PDL run on Linux? (And what about packages?)
401 Yes, PDL does run on Linux and indeed much of the development has been
403 done under Linux. On http://pdl.perl.org you can find links to packages
404 for some of the major distributions. Also check your distribution's
405 package manager (yum, apt, urpmi, ...) as PDL is now found by many of
406 these.
407 Q: 4.7 Does PDL run under Windows?
409 PDL builds fine on Win32 using MinGW or Microsoft compilers. See the
411 Win32/INSTALL file for details. Other compilers have not been
412 tested--input is welcome. A main worry on Windows platforms is the
413 lack of a good graphics interface, any help with this would be very
414 welcome.
415 There is also a distribution of PDL through ActiveState's ppm, though
417 it might not always be the latest version.
418
420 Q: 4.8 Can I get PDL via CVS?
421 Yes, as of December 1999, PDL is available at the CVS repository on
423 http://www.sourceforge.net . The tree is updated by developers who have
424 accounts on Sourceforge and snapshots of the tree are released regu‐
425 larly by the pumpkin holder (the pumpking).
426 If you wish to access the CVS repository and install PDL from there all
428 you need are two simple commands, however make sure you read some of
429 the documentation on Sourceforge as well for full information, but the
430 basic command is case sensitive and is:
431 cvs -d:pserver:anonymous@pdl.cvs.sourceforge.net:/cvsroot/pdl login
433 cvs -z3 -d:pserver:anonymous@pdl.cvs.sourceforge.net:/cvsroot/pdl co PDL
434 When prompted for a password just press the Enter key. Note however
436 that the CVS tree is to be considered a development release and as such
437 you are very welcome to try it out, but it is not recommended for mis‐
438 sion critical use and might crash unexpectedly.
439 Q: 4.9 I had a problem with the CVS version, how do I check if some‐
441 one has submitted a patch?
442 The Sourceforge system contains a patch-manager which contains patches
444 that have not yet been applied to the distribution. This can be
445 accessed by first accessing the Sourceforge web site and search for
446 PDL. This will show you the project page for PDL and will give you
447 access to the Patch manager.
448 In addition, if you are not subscribing to the mailing list, check the
450 archive of the " pdl-porters" and " perldl" mailing lists.
451 Q: 4.10 I have gotten developer access to CVS, but I have trouble
453 committing uploads.
454 The first you should do is to read the Sourceforge documentation and
456 learn the basics about CVS. But assuming you know this here is a quick
457 intro from Karl Glazebrook:
458 Delete your entire CVS directory structure and START AGAIN
460 (there is state)
461 In a clean directory:
463 setenv CVS_RSH ssh
465 setenv CVSROOT kgb@pdl.cvs.sourceforge.net:/cvsroot/pdl
466 cvs co PDL
468 You will need to type your password. every time you issue a cvs
470 command. there is no way around this if you use non-anon
471 access and you can't mix the two.
472 However cvs commits will now work and write back to the server.
474 You will continue to have to type your password until you upload
476 a key to the sourcefourge web page. Once you have done this it
477 becomes painless.
478
480 Q: 5.1 What is threading (is PDL a newsreader) ?
481 Unfortunately, in the context of PDL the term threading can have two
483 different (but related) meanings:
484 · When mentioned in the INSTALL directions and possibly during the
486 build process we have the usual computer science meaning of multi‐
487 threading in mind (useful mainly on multiprocessor machines or
488 clusters)
489 · PDL threading of operations on piddles (as mentioned in the index‐
491 ing docs) is the iteration of a basic operation over appropriate
492 subslices of piddles, e.g. the inner product " inner $a, $b" of a
493 (3) pdl $a and a (3,5,4) pdl $b results in a (5,4) piddle where
494 each value is the result of an inner product of the (3) pdl with a
495 (3) subslice of the (3,5,4) piddle. For details check PDL::Index‐
496 ing
497 PDL threading leads naturally to potentially parallel code which can
499 make use of multithreading on multiprocessor machines/networks; there
500 you have the connection between the two types of use of the term.
501 Q: 5.2 What is a piddle?
503 Well, PDL scalar variables (which are instances of a particular class
505 of perl objects, i.e. blessed thingies (see "man perlobj" )) are in
506 common PDL parlance often called piddles (for example, check the mail‐
507 ing list archives). Err, clear? If not, simply use the term piddle
508 when you refer to a PDL variable (an instance of a PDL object as you
509 might remember) regardless of what actual data the PDL variable con‐
510 tains.
511
513 Q: 6.1 What is perldl?
514 Sometimes perldl is used as a synonym for PDL. Strictly speaking, how‐
516 ever, the name perldl is reserved for the little shell that comes with
517 the PDL distribution and is supposed to be used for the interactive
518 prototyping of PDL scripts. For details check perldl.
519 Q: 6.2 How do I get online help for PDL?
521 Just type " help" (shortcut = "?") at the " perldl" prompt and proceed
523 from there. Another useful command is the " apropos" (shortcut = "??")
524 command. Also try the " demo" command in the perldl shell if you are
525 new to PDL.
526
528 Q: 6.3 I want to access the third element of a pdl but $a[2] doesn't
529 work ?!
530 See answer to the next question why the normal perl array syntax
532 doesn't work for pdls.
533 Q: 6.4 The docs say pdls are some kind of array. But why doesn't the
535 perl array syntax work with pdls then ?
536 Ok, you are right in a way. The docs say that pdls can be thought of
538 arrays. More specifically, it says ( PDL::Impatient ):
539 I find when using perlDL it is most useful to think of
541 standard perl @x variables as "lists" of generic
542 "things" and PDL variables like $x as
543 "arrays" which can be contained in lists or
544 hashes.
545 So, while pdls can be thought of as some kind of multi-dimensional
547 array they are not arrays in the perl sense. Rather, from the point of
548 view of perl they are some special class (which is currently imple‐
549 mented as an opaque pointer to some stuff in memory) and therefore need
550 special functions (or 'methods' if you are using the OO version) to
551 access individual elements or a range of elements. The functions/meth‐
552 ods to check are " at" / " set" (see the section 'Sections' in
553 PDL::Impatient ) or the powerful " slice" function and friends (see
554 PDL::Slices and PDL::Indexing ).
555 Finally, to confuse you completely, you can have perl arrays of pdls,
557 e.g. $spec[3] can refer to a pdl representing ,e.g, a spectrum, where
558 $spec[3] is the fourth element of the perl list (or array ;) @spec .
559 This may be confusing but is very useful !
560 Q: 6.5 How do I concatenate piddles?
562 Most people will try to form new piddles from old piddles using some
564 variation over the theme: " $a = pdl([$b, 0, 2])" , but this does not
565 work. The way to concatenate piddles is to use the function " cat" (see
566 also " append" and " glue"). Similarly you can split piddles using the
567 command " dog" .
568 Q: 6.6 Sometimes I am getting these strange results when using
570 inplace operations?
571 This question is related to the " inplace" function. From the documen‐
573 tation (see PDL::Impatient):
574 Most functions, e.g. log(), return a result which is
576 a transformation of their argument. This makes for
577 good programming practice. However many operations can
578 be done "in-place" and this may be required when large
579 arrays are in use and memory is at a premium. For these
580 circumstances the operator inplace() is provided which
581 prevents the extra copy and allows the argument to be
582 modified. e.g.:
583 $x = log($array); # $array unaffected
585 log( inplace($bigarray) ); # $bigarray changed in situ
586 And also from the doc !!:
588 Obviously when used with some functions which can
590 not be applied in situ (e.g. convolve()) unexpected
591 effects may occur!
592 Check the list of PDL functions at the end of PDL.pod which points out
594 " inplace" -safe functions.
595 Q: 6.7 What is this strange usage of the string concatenation opera‐
597 tor " .=" in PDL scripts?
598 See next question on assignment in PDL.
600 Q: 6.8 Why are there two different kinds of assignment in PDL ?
602 This is caused by the fact that currently the assignment operator " ="
604 allows only restricted overloading. For some purposes of PDL it turned
605 out to be necessary to have more control over the overloading of an
606 assignment operator. Therefore, PDL peruses the operator " .=" for cer‐
607 tain types of assignments.
608 Q: 6.9 How do I set a set of values in a piddle?
610 With versions of Perl prior to 5.6 this has to be done using a tempo‐
612 rary variable.
613 perldl> $a = sequence(5); p $a
615 [0 1 2 3 4]
616 perldl> $tmp = $a->slice('1:2'); p $tmp;
617 [1 2]
618 perldl> $tmp .= pdl([5, 6]); # Note .= !!
619 perldl> p $a
620 [0 5 6 3 4]
621 This can also be made into one expression, which is often seen in PDL
623 code:
624 perldl> ($tmp = $a->slice('1:2')) .= pdl([5,6])
626 perldl> p $a
627 [0 5 6 3 4]
628 In Perl 5.6 this assignment can be simplified using lvalue subroutines,
630 and this is now incorporated into PDL by requiring at least Perl 5.6.
631 Q: 6.10 Can I use a piddle in a conditional expression?
633 Yes you can, but not in the way you probably tried first. It is not
635 possible to use a piddle directly in a conditional expression since
636 this is usually poorly defined. Instead PDL has two very useful func‐
637 tions: " any" and " all" . Use these to test if any or all elements in
638 a piddle fulfils some criterion:
639 perldl> $a=pdl ( 1, -2, 3);
641 perldl> print '$a has at least one element < 0' if (any $a < 0);
642 $a has at least one element < 0
643 perldl> print '$a is not positive definite' unless (all $a > 0);
645 $a is not positive definite
646 Q: 6.11 Logical operators and piddles - '⎪⎪' and ' & & ' doesn't
648 work!
649 It is a common problem that you try to make a mask array or something
651 similar using a construct such as
652 $mask = which($piddle > 1 && $piddle < 2);
654 This does not work! What you are looking for is the bitwise logical
656 operators '⎪' and '&' which work on an element-by-element basis. So it
657 is really very simple: Do not use logial operators on multi-element
658 piddles since that really doesn't make sense, instead write the example
659 as:
660 $mask = which($piddle > 1 & $piddle < 2);
662 which works correctly.
664
666 Q: 6.12 What is a null pdl ?
667 " null" is a special token for 'empty piddle'. A null pdl can be used
669 to flag to a PDL function that it should create an appropriately sized
670 and typed piddle. Null piddles can be used in places where a PDL func‐
671 tion expects an output or temporary argument. Output and temporary
672 arguments are flagged in the signature of a PDL function with the "
673 [o]" and " [t]" qualifiers (see next question if you don't know what
674 the signature of a PDL function is). For example, you can invoke the
675 " sumover" function as follows:
676 sumover $a, $b=null;
678 which is equivalent to
680 $b = sumover $a;
682 If this seems still a bit murky check PDL::Indexing and PDL::PP for
684 details about calling conventions, the signature and threading (see
685 also below).
686 Q: 6.13 What is the signature of a PDL function ?
688 The signature of a function is an important concept in PDL. Many (but
690 not all) PDL function have a signature which specifies the arguments
691 and their (minimal) dimensionality. As an example, look at the signa‐
692 ture of the " maximum" function:
693 'a(n); [o] b;'
695 this says that " maximum" takes two arguments, the first of which is
697 (at least) one-dimensional while the second one is zero-dimensional and
698 an output argument (flagged by the " [o]" qualifier). If the function
699 is called with pdls of higher dimension the function will be repeatedly
700 called with slices of these pdls of appropriate dimension(this is
701 called threading in PDL).
702 For details and further explanations consult PDL::Indexing and PDL::PP
704 .
705 Q: 6.14 How can I subclass (inherit from) piddles?
707 The short answer is: read PDL::Objects (e.g. type " help PDL::Objects"
709 in the perldl shell).
710 The longer answer (extracted from PDL::Objects ): Since a PDL object is
712 an opaque reference to a C struct, it is not possible to extend the PDL
713 class by e.g. extra data via subclassing (as you could do with a hash
714 based perl object). To circumvent this problem PDL has built-in sup‐
715 port to extent the PDL class via the has-a relation for blessed
716 hashes. You can get the HAS-A behave like IS-A simply in that you
717 assign the PDL object to the attribute named " PDL" and redefine the
718 method initialize(). For example:
719 package FOO;
721 @FOO::ISA = qw(PDL);
723 sub initialize {
724 my $class = shift;
725 my $self = {
726 creation_time => time(), # necessary extension :-)
727 PDL => PDL->null, # used to store PDL object
728 };
729 bless $self, $class;
730 }
731 For another example check the script t/subclass.t in the PDL distribu‐
733 tion.
734 Q: 6.15 What on earth is this dataflow stuff ?
736 Dataflow is an experimental project that you don't need to concern
738 yourself with (it should not interfere with your usual programming).
739 However, if you want to know, have a look at PDL::Dataflow . There are
740 applications which will benefit from this feature (and it is already at
741 work behind the scenes).
742 Q: 6.16 What is PDL::PP?
744 Simple answer: PDL::PP is both a glue between external libraries and
746 PDL and a concise language for writing PDL functions.
747 Slightly longer answer: PDL::PP is used to compile very concise defini‐
749 tions into XSUB routines implemented in C that can easily be called
750 from PDL and which automatically support threading, dataflow and other
751 things without you having to worry about it.
752 For further details check PDL::PP and the section below on Extensions
754 of PDL.
755 Q: 6.17 What happens when I have several references to the same PDL
757 object in different variables (cloning, etc?) ?
758 Piddles behave like perl references in many respects. So when you say
760 $a = pdl [0,1,2,3];
762 $b = $a;
763 then both $b and $a point to the same object, e.g. then saying
765 $b++;
767 will *not* create a copy of the original piddle but just increment in
769 place, of which you can convince yourself by saying
770 print $a;
772 [1 2 3 4]
773 This should not be mistaken for dataflow which connects several *dif‐
775 ferent* objects so that data changes are propagated between the so
776 linked piddles (though, under certain circumstances, dataflown piddles
777 can share physically the same data).
778 It is important to keep the "reference nature" of piddles in mind when
780 passing piddles into subroutines. If you modify the input pdls you mod‐
781 ify the original argument, not a copy of it. This is different from
782 some other array processing languages but makes for very efficient
783 passing of piddles between subroutines. If you do not want to modify
784 the original argument but rather a copy of it just create a copy
785 explicitly (this example also demonstrates how to properly check for an
786 explicit request to process inplace, assuming your routine can work
787 inplace):
788 sub myfunc {
790 my $pdl = shift;
791 if ($pdl->is_inplace)
792 {$pdl->set_inplace(0)}
793 else # modify a copy by default
794 {$pdl = $pdl->copy}
795 $pdl->set(0,0);
796 return $pdl;
797 }
798
800 Q: 6.18 What I/O formats are supported by PDL ?
801 The current versions of PDL already support quite a number of different
803 I/O formats. However, it is not always obvious which module implements
804 which formats. To help you find the right module for the format you
805 require, here is a short list of the current list of I/O formats and a
806 hint in which module to find the implementation:
807 · A home brew fast raw (binary) I/O format for PDL is implemented by
809 the FastRaw module
810 · The FlexRaw module implements generic methods for the input and
812 output of `raw' data arrays. In particular, it is designed to read
813 output from FORTRAN 77 UNFORMATTED files and the low-level C write
814 function, even if the files are compressed or gzipped.
815 It is possible that the FastRaw functionality will be included in
817 the FlexRaw module at some time in the future.
818 · FITS I/O is implemented by the wfits/rfits functions in
820 PDL::IO::Misc.
821 · Ascii file I/O in various formats can be achieved by using the "
823 rcols" and " rgrep" functions, also in PDL::IO::Misc.
824 · PDL::IO::Pic implements an interface to the netpbm/pbm+ filters to
826 read/write several popular image formats; also supported is output
827 of image sequences as MPEG movies.
828 · On CPAN you can find the PDL-NetCDF module that works with the cur‐
830 rent released version of PDL 2.4.3.
831 For further details consult the documentation in the individual mod‐
833 ules.
834 Q: 6.19 How can I stack a set of 2D arrays (images) into a 3D pid‐
836 dle?
837 Assuming all arrays are of the same size and in some format recognised
839 by rpic (see PDL::IO::Pic ) you could say:
840 use PDL::IO::Pic;
842 @names = qw/name1.tif .... nameN.tif/; # some file names
843 $dummy = PDL->rpic($names[0]);
844 $cube = PDL->zeroes($dummy->type,$dummy->dims,$#names+1); # make 3D piddle
845 for (0..$#names)
846 {($tmp = $cube->slice(":,:,($_)")) .= PDL->rpic($names[$_])}
847 The for loop reads the actual images into a temporary 2D piddle whose
849 values are then assigned (using the overloaded " .=" operator) to the
850 approriate slices of the 3D piddle $cube .
851 Q: 6.20 Where are testfiles for the graphics modules?
853 This answer applies mainly to PDL::Graphics::TriD (PDL's device inde‐
855 pendent 3D graphics model) which is the trickiest one in this respect.
856 You find some test scripts in Demos/TriD in the distribution. After you
857 have built PDL just change to that directory and try
858 perl -Mblib <testfile>
860 where " < testfile "> ; should match the pattern " test[3-9].p" and
862 watch the results. Some of the tests should bring up a window where you
863 can control (twiddle) the 3D objects with the mouse. Try using MB1 for
864 turning the objects in 3D space, MB3 to zoom in and out, and 'q' to
865 advance to the next stage of the test.
866 If you have a VRML viewer plugin for netscape you can also try "
868 tvrml*.p" for PDL generated dynamic VRML.
869 Some demos of 3D graphics with PDL can also be invoked using the "
871 demo" command within the perldl shell.
872 Q: 6.21 What is TriD or PDL::TriD or PDL::Graphics::TriD?
874 Questions like this should be a thing of the past with the PDL online
876 help system in place. Just try (after installation):
877 un*x> perldl
879 perldl> apropos trid
880 Check the output for promising hits and then try to look up some of
882 them, e.g.
883 perldl> help PDL::Graphics::TriD
885 Note that case matters with " help" but not with " apropos" .
887 Q: 6.22 PGPLOT does not write out PNG files.
889 There are a few sources of trouble with PGPLOT and PNG files. First,
891 when compiling the pgplot libraries, make sure you uncommented the PNG
892 entries in the drivers.list file. Then when running 'make' you probably
893 got an error like
894 "make: *** No rule to make target `png.h', needed by `pndriv.o'.
896 Stop."
897 To fix this, find the line in the 'makefile' that starts with
899 'pndriv.o:' (it's near the bottom). Change, for example, ./png.h to
900 /usr/include/png.h, if that is where your header files are (you do have
901 the libpng and libz devel packages, don't you?). Do this for all four
902 entries on that line, then go back and run "make".
903 Second, if you already have the PGPLOT Perl module and PDL installed,
905 you probably tried to write out a png file and got fatal error message
906 like:
907 "undefined symbol: png_create_write_struct"
909 This is because the PGPLOT perl module does not automatically link
911 against the png and z libraries. So when you are installing the PGPLOT
912 perl module (version 2.19) from CPAN, don't do "install PGPLOT", but
913 just do "get PGPLOT". Then exit from CPAN and manually install PGPLOT,
914 calling the makefile thusly:
915 "perl Makefile.PL EXLIB=png,z EXDIR=/usr/lib"
917 assuming that there exist files such as /usr/lib/libpng.so.*,
919 /usr/lib/libz.so.*. Then do the standard "make;make test;make install;"
920 sequence. Now you can write png files from PDL!
921
923 Q: 7.1 I am looking for a package to do XXX in PDL. Where shall I
924 look for it?
925 The first stop is again " perldl" or the PDL documentation. There is
927 already a lot of functionality in PDL which you might be aware of. The
928 easiest way to look for functionality is to use the " apropos" command:
929 perldl> apropos 'integral'
931 ceil Round to integral values in floating-point format
932 floor Round to integral values in floating-point format
933 intover Project via integral to N-1 dimensions
934 rint Round to integral values in floating-point format
935 Since the apropos command is no sophisticated search engine make sure
937 that you search on a couple of related topics and use short phrases.
938 However there is a good chance that what you need is not part of the
940 PDL distribution. You are then well advised to check out
941 http://pdl.perl.org where there is a list of packages using PDL. If
942 that does not solve your problem, ask on the mailing-list, if nothing
943 else you might get assistance which will let you interface your package
944 with PDL yourself, see also the next question.
945 Q: 7.2 Can I access my C/Fortran library routines in PDL?
947 Yes, you can, in fact it is very simple for many simple applications.
949 What you want is the PDL pre-prosessor PP (PDL::PP ). This will allow
950 you to make a simple interface to your C routine.
951 The two functions you need to learn (at least first) are " pp_def"
953 which defines the calling interface to the function, specifying input
954 and output parameters, and contains the code that links to the external
955 library. The other command is " pp_end" which finishes the PP defini‐
956 tions. For details see the PDL::PP man-page, but we also have a worked
957 example here.
958 double eight_sum(int n)
960 {
961 int i;
962 double sum, x;
963 sum = 0.0; x=0.0;
965 for (i=1; i<=n; i++) {
966 x++;
967 sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
968 }
969 return 1.0/sum;
970 }
971 We will here show you an example of how you interface C code with PDL.
973 This is the first example and will show you how to approximate the num‐
974 ber 8...
975 The C code is shown above and is a simple function returning a double,
977 and expecting an integer - the number of terms in the sum - as input.
978 This function could be defined in a library or, as we do here, as an
979 inline function.
980 We will postpone the writing of the Makefile till later. First we will
982 construct the " .pd" file. This is the file containing PDL::PP code. We
983 call this " eight.pd" .
984 #
986 # pp_def defines a PDL function.
987 #
988 pp_addhdr (
989 '
990 double eight_sum(int n)
991 {
992 int i;
993 double sum, x;
994 sum = 0.0; x=0.0;
996 for (i=1; i<=n; i++) {
997 x++;
998 sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
999 }
1000 return 1.0/sum;
1001 }
1003 ');
1004 pp_def (
1006 'eight',
1007 Pars => 'int a(); double [o]b();',
1008 Code => '$b()=eight_sum($a());'
1009 );
1010 # Always make sure that you finish your PP declarations with
1012 # pp_done
1013 pp_done();
1015 A peculiarity with our example is that we have included the entire code
1017 with " pp_addhdr" instead of linking it in. This is only for the pur‐
1018 poses of example, in a typical application you will use " pp_addhdr" to
1019 include header files. Note that the argument to " pp_addhdr" is
1020 enclosed in quotes.
1021 What is most important in this example is however the " pp_def" com‐
1023 mand. The first argument to this is the name of the new function eight
1024 , then comes a hash which the real meat:
1025 · This gives the input parameters (here " a" ) and the output parame‐
1027 ters (here " b" ). The latter are indicated by the " [o]" speci‐
1028 fier. Both arguments can have a type specification as shown here.
1029 Many variations and further flexibility in the interface can be
1031 specified. See the manpage for details.
1032 · This switch contains the code that should be executed. As you can
1034 see this is a rather peculiar mix of C and Perl, but essentially it
1035 is just as you would write it in C, but the variables that are
1036 passed from PDL are treated differently and have to be referred to
1037 with a preceding '$'.
1038 There are also simple macros to pass pointers to data and to obtain
1040 the values of other Perl quantities, see the manual page for fur‐
1041 ther details.
1042 Finally note the call to " pp_done()" at the end of the file. This is
1044 necessary in all PP files.
1045 Ok. So now we have a file with code that we dearly would like to use in
1047 Perl via PDL. To do this we need to compile the function, and to do
1048 that we need a Makefile.
1049 use PDL::Core::Dev;
1051 use ExtUtils::MakeMaker;
1052 PDL::Core::Dev->import();
1053 $package = ["eight.pd",Eight,PDL::Eight];
1055 %hash = pdlpp_stdargs($package);
1056 WriteMakefile( %hash );
1058 sub MY::postamble {pdlpp_postamble($package)};
1060 The code above should go in a file called Makefile.PL, which should
1062 subsequently be called in the standard Perl way: " perl Makefile.PL" .
1063 This should give you a Makefile and running " make" should compile the
1064 module for you and " make install" will install it for you.
1065 Q: 7.3 How can I interface package XXX in PDL?
1067 This question is closely related to the previous one, and as we said
1069 there, the PDL::PP pre-processor is the standard way of interfacing
1070 external packages with PDL. The most usual way to use PDL::PP is to
1071 write a short interface routine, see the PDL::PP manpage and the answer
1072 to the previous question for examples.
1073 However it is also possible to interface a package to PDL by re-writing
1075 your function in PDL::PP directly. This can be convenient in certain
1076 situations, in particular if you have a routine that expects a function
1077 as input and you would like to pass the function a Perl function for
1078 convenience.
1079 The PDL::PP manpage is the main source of information for writing
1081 PDL::PP extensions, but it is very useful to look for files in the dis‐
1082 tribution of PDL as many of the core functions are written in PDL::PP.
1083 Look for files that end in " .pd" which is the generally accepted suf‐
1084 fix for PDL::PP files. But we also have a simple example here.
1085 The following example will show you how to write a simple function that
1087 automatically allows threading. To make this concise the example is of
1088 an almost trivial function, but the intention is to show the basics of
1089 writing a PDL::PP interface.
1090 We will write a simple function that calculates the minimum, maximum
1092 and average of a piddle. On my machine the resulting function is 8
1093 times faster than the built-in function " stats" (of course the latter
1094 also calculates the median).
1095 Let's jump straight in. Here is the code (from a file called " quick‐
1097 stats.pd" )
1098 #
1100 pp_def('quickstats',
1101 Pars => 'a(n); [o]avg(); [o]max(); [o]min()',
1102 Code => '$GENERIC(a) curmax, curmin;
1103 $GENERIC(a) tmp=0;
1104 loop(n) %{
1105 tmp += $a();
1106 if (!n ⎪⎪ $a() > curmax) { curmax = $a();}
1107 if (!n ⎪⎪ $a() < curmin) { curmin = $a();}
1108 %}
1109 $avg() = tmp/$SIZE(n);
1110 $max() = curmax;
1111 $min() = curmin;
1112 '
1113 );
1114 pp_done();
1116 The above might look like a confusing mixture of C and Perl, but behind
1118 the peculiar syntax lies a very powerful language. Let us take it line
1119 by line.
1120 The first line declares that we are starting the definition of a PDL:PP
1122 function called " quickstats" .
1123 The second line is very important as it specifies the input and output
1125 parameters of the function. a(n) tells us that there is one input
1126 parameter that we will refer to as " a" which is expected to be a vec‐
1127 tor of length n (likewise matrices, both square and rectangular would
1128 be written as " a(n,n)" and " a(n,m)" respectively). To indicate that
1129 something is an output parameter we put " [o]" in front of their names,
1130 so referring back to the code we see that avg, max and min are three
1131 output parameters, all of which are scalar (since they have no dimen‐
1132 sional size indicated.
1133 The third line starts the code definition which is essentially pure C
1135 but with a couple of convenient functions. $GENERIC is a function
1136 that returns the C type of its argument - here the input parameter a.
1137 Thus the first two lines of the code section are variable declarations.
1138 The loop(n) construct is a convenience function that loops over the
1140 dimension called n in the parameter section. Inside this loop we calcu‐
1141 late the cumulative sum of the input vector and keep track of the maxi‐
1142 mum and minimum values. Finally we assign the resulting values to the
1143 output parameters.
1144 Finally we finish our function declaration with " pp_done()" .
1146 To compile our new function we need to create a Makefile, which we will
1148 just list since its creation is discussed in an earlier question.
1149 use PDL::Core::Dev;
1151 use ExtUtils::MakeMaker;
1152 PDL::Core::Dev->import();
1153 $package = ["quickstats.pd",Quickstats,PDL::Quickstats];
1155 %hash = pdlpp_stdargs($package);
1156 WriteMakefile( %hash );
1158 sub MY::postamble {pdlpp_postamble($package)};
1160 An example Makefile.PL
1162 Our new statistic function should now compile using the tried and
1164 tested perl way: " perl Makefile.PL; make" .
1165 You should experiment with this function, changing the calculations and
1167 input and output parameters. In conjunction with the PDL::PP manpage
1168 this should allow you to quickly write more advanced routines directly
1169 in PDL::PP.
1170
1173 ·
1174 · General minor update: mailing list info, links, version, date,
1175 some text.
1176 · Removed FAQ maintainer.
1178 ·
1180 · markers for alpha stage functionality removed
1181 · restructured description
1183 · development/support of PDL
1185 · PDL and online help
1187 · subclassing piddles
1189 · new INSTALLATION section
1191 · how to stack 2D piddles - > 3D piddle
1193 · questions regarding TriD
1195 ·
1197 · use of perl5.004 is now required
1198 · PDL I/O formats
1200 · piddles behave like perl references
1202 · null PDL's and output arguments
1204 · signature
1206 ·
1208 · questions about pdls and perl array syntax
1209 · added requirement for C compiler in answer to 'what
1211 machines...' question
1212 · PDL jargon section
1214 · piddles
1216 ·
1218 · upgraded released/alpha version numbers
1219 · added another WYANDL reason
1221 · split into perldl/pdl-porters mailing lists
1223 ·
1225 · initial revision
1226
1228 If you find any inaccuracies in this document (or disfunctional URLs)
1229 please report to the perldl mailing list perldl@jach.hawaii.edu.
1230
1232 Achim Bohnet (ach@mpe.mpg.de ) for suggesting CoolHTML as a prettypod‐
1233 der (although we have switched to XML now) and various other improve‐
1234 ments. Suggestions for some questions were taken from Perl Faq and
1235 adapted for PDL.
1236
1238 Many people have contributed or given feedback on the current version
1239 of the FAQ, here is an incomplete list of individuals whose contribu‐
1240 tions or posts to the mailing-list have improved this FAQ at some point
1241 in time alphabetically listed by first name: Christian Soeller, Doug
1242 Burke, Doug Hunt, Frank Schmauder, Jarle Brinchmann, John Cerney, Karl
1243 Glazebrook, Kurt Starsinic, Thomas Yengst, Tuomas J. Lukka.
1244
1246 This document emerged from a joint effort of several PDL developers
1247 (Karl Glazebrook ( kgb@aaoepp.aao.gov.au ), Tuomas J. Lukka (
1248 lukka@iki.fi ), Christian Soeller ( c.soeller@auckland.ac.nz )) to com‐
1249 pile a list of the most frequently asked questions about PDL with
1250 answers. Permission is granted for verbatim copying (and formatting)
1251 of this material as part of PDL. Permission is explicitly not granted
1252 for distribution in book or any corresponding form. Ask on the PDL
1253 mailing list perldl@jach.hawaii.edu if some of the issues covered in
1254 here are unclear.
1255perl v5.8.8 2003-05-21 FAQ(1)