1FAQ(1) User Contributed Perl Documentation FAQ(1)
2
3
4
6 PDL::FAQ - Frequently asked questions about PDL
7
9 Current FAQ version: 0.93
10
12 This is version 0.93 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
18 http://pdl.sourceforge.net/FAQ .
19
20 Q: 1.2 How to contribute to this document
21 This is a considerably reworked version of the PDL FAQ. As such many
22 errors might have crept in and many updates might not have made it in.
23 You are explicitly encouraged to let us know about questions which you
24 think should be answered in this document but currently aren't.
25 Similarly, if you think parts of this document are unclear, please tell
26 the FAQ maintainer about it. Where a specific answer is taken in full
27 from someone's posting the authorship should be indicated, let the FAQ
28 maintainer know if it isn't. For more general information explicit
29 acknowledgement is not made in the text, but rather there is an
30 incomplete list of contributors at the end of this docuement. Please
31 contact the FAQ maintainer if you feel hard done by.
32
33 Send your comments, additions, suggestions or corrections to the PDL
34 mailing list at perldl@jach.hawaii.edu. See below for instructions on
35 how to join the mailing lists.
36
38 Q: 2.1 What is PDL ?
39 PDL stands for Perl Data Language . To say it with the words of Karl
40 Glazebrook, initiator of the PDL project:
41
42 The PDL concept is to give standard perl5 the ability
43 to COMPACTLY store and SPEEDILY manipulate the large
44 N-dimensional data sets which are the bread and butter
45 of scientific computing. e.g. $a=$b+$c can add two
46 2048x2048 images in only a fraction of a second.
47
48 It provides tons of useful functionality for scientific and numeric
49 analysis.
50
51 For readers familiar with other scientific data evaluation packages it
52 may be helpful to add that PDL is in many respects similar to IDL,
53 MATLAB and similar packages. However, it tries to improve on a number
54 of issues which were perceived (by the authors of PDL) as shortcomings
55 of those existing packages.
56
57 Q: 2.2 Who supports PDL? Who develops it?
58 PDL is supported by its users. General informal support for PDL is
59 provided through the PDL mailing list (perldl@jach.hawaii.edu , see
60 below).
61
62 As a Perl extension (see below) it is devoted to the idea of free and
63 open development put forth by the Perl community. PDL was and is being
64 actively developed by a loosely knit group of people around the world
65 who coordinate their activities through the PDL development mailing
66 list (pdl-porters@jach.hawaii.edu , see below). If you would like to
67 join in the ongoing efforts to improve PDL please join this list.
68
69 Q: 2.3 Why yet another Data Language ?
70 There are actually several reasons and everyone should decide for
71 himself which are the most important ones:
72
73 · PDL is "free software". The authors of PDL think that this concept
74 has several advantages: everyone has access to the sources ->
75 better debugging, easily adaptable to your own needs, extensible
76 for your purposes, etc... In comparison with commercial packages
77 such as Matlab and IDL this is of considerable importance for
78 workers who want to do some work at home and cannot afford the
79 considerable cost to buy commercial packages for personal use.
80
81 · PDL is based on a powerful and well designed scripting language:
82 Perl. In contrast to other scientific/numeric data analysis
83 languages it has been designed using the features of a proven
84 language instead of having grown into existence from scratch.
85 Defining the control structures while features were added during
86 development leads to languages that often appear clumsy and badly
87 planned for most existing packages with similar scope as PDL.
88
89 · Using Perl as the basis a PDL programmer has all the powerful
90 features of Perl at his hand, right from the start. This includes
91 regular expressions, associative arrays (hashes), well designed
92 interfaces to the operating system, network, etc. Experience has
93 shown that even in mainly numerically oriented programming it is
94 often extremely handy if you have easy access to powerful semi-
95 numerical or completely non-numerical functionality as well. For
96 example, you might want to offer the results of a complicated
97 computation as a server process to other processes on the network,
98 perhaps directly accepting input from other processes on the
99 network. Using Perl and existing Perl extension packages things
100 like this are no problem at all (and it all will fit into your "PDL
101 script").
102
103 · Extremely easy extensibility and interoperability as PDL is a Perl
104 extension; development support for Perl extensions is an integral
105 part of Perl and there are already numerous extensions to standard
106 Perl freely available on the network.
107
108 · Integral language features of Perl (regular expressions, hashes,
109 object modules) immensely facilitated development and
110 implementation of key concepts of PDL. One of the most striking
111 examples for this point is probably PDL::PP (see below), a code
112 generator/parser/pre-processor that generates PDL functions from
113 concise descriptions.
114
115 · None of the existing DLs follow the Perl language rules, which the
116 authors firmly believe in:
117
118 · TIMTOWTDI: There is more than one way to do it. Minimalist
119 languages are interesting for computer scientists, but for
120 users, a little bit of redundancy makes things wildly easier to
121 cope with and allows individual programming styles - just as
122 people speak in different ways. For many people this will
123 undoubtedly be a reason to avoid PDL ;)
124
125 · Simple things are simple, complicated things possible: Things
126 that are often done should be easy to do in the language,
127 whereas seldom done things shouldn't be too cumbersome.
128
129 All existing languages violate at least one of these rules.
130
131 · As a project for the future PDL should be able to use super
132 computer features, e.g. vector capabilities/parallel processing,
133 GPGPU acceleration. This will probably be achieved by having
134 PDL::PP (see below) generate appropriate code on such architectures
135 to exploit these features.
136
137 · [ fill in your personal 111 favourite reasons here...]
138
139 Q: 2.4 What is PDL good for ?
140 Just in case you do not yet know what the main features of PDL are and
141 what one could do with them, here is a (necessarily selective) list of
142 key features:
143
144 PDL is well suited for matrix computations, general handling of
145 multidimensional data, image processing, general scientific
146 computation, numerical applications. It supports I/O for many popular
147 image and data formats, 1D (line plots), 2D (images) and 3D (volume
148 visualisation, surface plots via OpenGL - for instance implemented
149 using Mesa or video card OpenGL drivers), graphics display capabilities
150 and implements many numerical and semi-numerical algorithms.
151
152 Through the powerful pre-processor it is also easy to interface Perl to
153 your favourite C routines, more of that further below.
154
155 Q: 2.5 What is the connection between PDL and Perl ?
156 PDL is a Perl5 extension package. As such it needs an existing Perl5
157 installation (see below) to run. Furthermore, much of PDL is written in
158 perl (+ some core functionality that is written in C). PDL programs are
159 (syntactically) just perl scripts that happen to use some of the
160 functionality implemented by the package "PDL".
161
162 Q: 2.6 What do I need to run PDL on my machine ?
163 Since PDL is just a Perl package you need first of all an installation
164 of Perl on your machine. As of this writing PDL requires version 5.6.2
165 of Perl, version 5.8 or higher is strongly recommended. More
166 information on where and how to get a Perl installation can be found at
167 the Perl home page http://www.perl.org and at many CPAN sites (if you
168 do not know what CPAN is check the answer to the next question).
169
170 To build PDL you also need a working C compiler and support for Xsubs
171 the package Extutils::MakeMaker. If you don't have a compiler there
172 might be a binary distribution available, see "Binary distributions"
173 below.
174
175 If you can (or cannot) get PDL working on a new (previously
176 unsupported) platform we would like to hear about it. Please, report
177 your success/failure to the PDL mailing list at perldl@jach.hawaii.edu
178 . We will do our best to assist you in porting PDL to a new system.
179
180 Q: 2.7 Where do I get it?
181 PDL is available as source distribution in the Comprehensive Perl
182 Archive Network , or CPAN. This archive contains not only the PDL
183 distribution but also just about everything else that is Perl-related.
184 CPAN is mirrored by dozens of sites all over the world. The main site
185 is http://www.cpan.org , and local CPAN sites (mirrors) can be found
186 there. Within CPAN you find the latest released version of PDL in the
187 directory /modules/by-module/PDL/. PDLs homepage is at
188 http://pdl.perl.org and the latest version can also be downloaded from
189 there.
190
191 [ Need to update with information for win32 ]
192
193 Q: 2.8 What do I have to pay to get PDL?
194 We are delighted to be able to give you the nicest possible answer on a
195 question like this: PDL is *free software* and all sources are publicly
196 available. But still, there are some copyrights to comply with. So
197 please, try to be as nice as we (the PDL authors) are and try to comply
198 with them.
199
200 Oh, before you think it is *completely* free: you have to invest some
201 time to pull the distribution from the net, compile and install it and
202 (maybe) read the manuals.
203
205 Q: 3.1 Where can I get information on PDL?
206 The complete PDL documentation is available with the PDL distribution.
207 If you have PDL installed on your machine and are on a unix like system
208 then you can read the PDL manuals with the " man" command. " man PDL"
209 get you started, " man PDL::FAQ" will let you read this document, etc.
210 In any case (i.e. also on non-unixes) " perldoc PDL::Intro" should
211 work, and if you don't want to type that much, " pdldoc intro" should
212 also work.
213
214 The easiest way by far, however, to get familiar with PDL is to use the
215 PDL online help facility from within the " perldl" shell. Just type "
216 perldl" at your system prompt. Once you are inside the " perldl" shell
217 type " help" . Using the " help" and " apropos" commands inside the
218 shell you should be able to find the way round the documentation. Even
219 better, you can immediately try your newly acquired knowledge about PDL
220 by issuing PDL/perl commands directly at the command line. To
221 illustrate this process, here is the record of a typical perldl session
222 of a PDL beginner (lengthy output is only symbolically reproduced in
223 braces ( <... ...> ) ):
224
225 unix> perldl
226 perldl> help
227 <.... help output ....>
228 perldl> help PDL::Impatient
229 <.... man page ....>
230 perldl> $a = pdl (1,5,7.3,1.0)
231 perldl> $b = sequence float, 4, 4
232 perldl> help inner
233 <.... help on the 'inner' function ....>
234 perldl> $c = inner $a, $b
235 perldl> p $c
236 [22.6 79.8 137 194.2]
237
238 For further sources of information that are accessible through the
239 internet see next question.
240
241 Q: 3.2 Are there other PDL information sources on the internet?
242 First of all, for all purely Perl-related questions there are tons of
243 sources on the net. Good points to start are http://www.perl.com and
244 http://www.perl.org .
245
246 The PDL home site can be accessed by pointing your web browser to
247 http://pdl.perl.org . It has tons of goodies for anyone interested in
248 PDL:
249
250 · PDL distributions
251
252 · Online documentation
253
254 · Pointers to an HTML archive of the PDL mailing lists
255
256 · A list of platforms on which PDL has been successfully tested.
257
258 · News about recently added features, ported libraries, etc.
259
260 · Name of the current pumpkin holders for the different PDL modules
261 (if you want to know what that means you better had a look at the
262 web pages).
263
264 If you are interested in PDL in general you can join the PDL mailing
265 list perldl@jach.hawaii.edu. This is a forum to discuss programming
266 issues in PDL, report bugs, seek assistance with PDL related problems,
267 etc. To subscribe, fill out the form at
268 http://mailman.jach.hawaii.edu/mailman/listinfo/perldl .
269
270 A searchable archive and a hypertext version of the traffic on this
271 list (1997-2004) can be found at
272 http://www.xray.mpe.mpg.de/mailing-lists/perldl/ . More recent messages
273 (since June 2005) can be found at
274 http://mailman.jach.hawaii.edu/mailman/listinfo/perldl .
275
276 If you are interested in all the technical details of the ongoing PDL
277 development you can join the PDL developers mailing list
278 pdl-porters@jach.hawaii.edu . To subscribe, fill out the form at
279 http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters .
280
281 A searchable archive and a hypertext version of the traffic on this
282 list (1997-2004) can be found at
283 http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/ . More recent
284 messages (since June 2005) can be found at
285 http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters .
286
287 Crossposting between these lists should be avoided unless there is a
288 very good reason for doing that.
289
290 Q: 3.3 What is the current version of PDL ?
291 As of this writing (FAQ version 0.93 of 01 Jan 2010) the latest stable
292 version is 2.4.6. The latest stable version should always be available
293 from a CPAN mirror site near you (see Question 2.7 for info on where to
294 get PDL.
295
296 The most current (possibly unstable) version of PDL can be obtained
297 from the Git repository, see Question 4.10 and periodic CPAN developers
298 releases of the Git code will be made for testing purposes and more
299 general availability. The second PDL-2.4.6 prerelease candidate is
300 available via git or as a CPAN developers release:
301 CHM/PDL-2.4.5_008.tar.gz .
302
303 Q: 3.4 I want to contribute to the further development of PDL. How can I
304 help?
305 If you have a certain project in mind you should check if somebody else
306 is already working on it or if you could benefit from existing modules.
307 Do so by posting your planned project to the PDL developers mailing
308 list at pdl-porters@jach.hawaii.edu . See the subscription instructions
309 in Question 3.2. We are always looking for people to write code and/or
310 documentation ;).
311
312 Q: 3.5 I think I have found a bug in the current version of PDL. What
313 shall I do?
314 First, make sure that the bug/problem you came across has not already
315 been dealt with somewhere else in this FAQ. Secondly, you can check
316 the searchable archive of the PDL mailing lists to find whether this
317 bug has already been discussed. If you still haven't found any
318 explanations you can post a bug report to perldl@jach.hawaii.edu , or
319 through the Bugs link on http://pdl.perl.org . See the BUGS file in
320 the PDL distribution for what information to include. If you are
321 unsure, discussions via the perldl mailing list can be most helpful.
322
324 Q: 4.1 I have problems installing PDL. What shall I do?
325 First make sure you have read the file INSTALL in the distribution.
326 This contains a list of common problems which are unnecessary to repeat
327 here.
328
329 Next, check the file perldl.conf to see if by editing the configuration
330 options in that file you will be able to successfully build PDL. Some
331 of the modules need additional software installed, please refer to the
332 file DEPENDENCIES for further details. Make sure to edit the location
333 of these packages in perldl.conf if you have them in non-standard
334 locations.
335
336 N.B. Unix shell specific: If you would like to save an edited
337 perldl.conf for future builds just copy it as ~/.perldl.conf into your
338 home directory where it will be picked up automatically during the PDL
339 build process.
340
341 Also, check for another, pre-existing version of PDL on the build
342 system. Multiple PDL installs in the same PATH or @INC can cause
343 puzzling test or build failures.
344
345 If you still can't make it work properly please submit a bug report
346 including detailed information on the problems you encountered to the
347 perldl mailing list ( perldl@jach.hawaii.edu , see also above).
348 Response is often rapid.
349
350 Q: 4.2 Are there configuration files for PDL I have to edit?
351 Most users should not have to edit any configuration files manually.
352 However, in some cases you might have to supply some information about
353 akwardly placed include files/libraries or you might want to explicitly
354 disable building some of the optional PDL modules. Check the files
355 INSTALL and perldl.conf for details.
356
357 If you had to manually edit perldl.conf and are happy with the results
358 you can keep the file handy for future reference. Place it in
359 ~/.perldl.conf where it will be picked up automatically or use " perl
360 Makefile.PL PDLCONF=your_file_name" next time you build PDL.
361
362 Q: 4.3 Do I need other software for successfull operation?
363 For the basic PDL functionality you don't need any additional software.
364 However, some of the optional PDL modules included in the distribution
365 (notably most graphics and some I/O modules) require certain other
366 libraries/programs to be installed. Check the file DEPENDENCIES in the
367 distribution for details and directions on how to get these.
368
369 Q: 4.4 How can I install PDL in a non-standard location?
370 To install PDL in a non-standard location, use the PREFIX and LIB
371 options in the " perl Makefile.PL" configure step. For example, " perl
372 Makefile.PL PREFIX=/myprefix LIB=/myprefix/lib/perl5" will configure
373 PDL to install the perl code into the /myprefix/lib/perl5 and the
374 system install files like binary executables in the directories "
375 /myprefix/bin, /myprefix/lib, /myprefix/include...".
376
377 Q: 4.5 How can I force a completely clean installation?
378 To guarantee a completely clean installation of PDL, you will need to
379 first delete the current installation files and folders. These will be
380 all directories named " PDL" in the perl @INC path, files named "
381 *Pdlpp*" in any " Inline" directories, and the programs " pdl, pdldoc,
382 perldl, and pptemplate". Then just build and install as usual. This
383 is much easier to keep track of if you always install " PDL" into a
384 non-standard location. See FAQ 4.4 above.
385
387 Q: 4.5 What binary distributions are available?
388 Information about binary distributions of PDL can be found on
389 http://pdl.perl.org . At present there are binary distributions of PDL
390 for Linux (RedHat and Debian), FreeBSD, Mac OS X and Windows, though
391 they might not be the most recent version. If someone is interested in
392 providing binary distributions for other architectures, that would be
393 very welcome. Let us know on the pdl-porters@jach.hawaii.edu mailing
394 list. Also check your Linux distibution's package manager as many now
395 include PDL. PPMs for win32 versions are also available.
396
397 Q: 4.6 Does PDL run on Linux? (And what about packages?)
398 Yes, PDL does run on Linux and indeed much of the development has been
399 done under Linux. On http://pdl.perl.org you can find links to packages
400 for some of the major distributions. Also check your distribution's
401 package manager (yum, apt, urpmi, ...) as PDL is now found by many of
402 these.
403
404 Q: 4.7 Does PDL run under Windows?
405 PDL builds fine on Win32 using MinGW or Microsoft compilers. See the
406 Win32/INSTALL file for details. Other compilers have not been
407 tested--input is welcome. There is also a distribution of PDL through
408 ActiveState's ppm, though it might not always be the latest version.
409
411 Q: 4.8 Can I get PDL via CVS?
412 No. PDL development was conducted with a CVS repository from December
413 1999 to April 2009. In April 2009 the project switched to the Git
414 <http://git-scm.com> source control management system. Note that some
415 auxiliary project repositories (the project website, some books, etc.)
416 are still available via CVS.
417
418 Q: 4.9 How do I get PDL via Git?
419 Assume you have Git installed on your system and want to download the
420 project source code into the directory "PDL". To get read-only access
421 to the repository, you type at the command line
422
423 git clone git://pdl.git.sourceforge.net/gitroot/pdl/pdl PDL
424
425 To get developer read/write access to the repository type at the
426 command line
427
428 git clone ssh://USERNAME@pdl.git.sourceforge.net/gitroot/pdl/pdl PDL
429
430 Q: 4.10 I had a problem with the Git version, how do I check if someone
431 has submitted a patch?
432 The Sourceforge system contains a patch-manager which contains patches
433 that have not yet been applied to the distribution. This can be
434 accessed via the Tracker at PDL's Sourceforge project page
435 http://sourceforge.net/projects/pdl .
436
437 In addition, if you are not subscribing to the mailing list, check the
438 archive of the " pdl-porters" and " perldl" mailing lists.
439
440 Q: 4.11 I have gotten developer access to Git, how do I upload my
441 changes?
442 The first thing you should do is to read the Git documentation and
443 learn the basics about Git. There are links to this information from
444 PDL's SF Git page http://sourceforge.net/scm/?type=git&group_id=612 .
445 But here are the basics:
446
447 Before you upload your changes, commit them to YOUR repository
448
449 git add <file1> <file2> ...
450 git commit
451
452 or combine these two with
453
454 git commit -a
455
456 Then pull in any changes others have made
457
458 git pull origin
459
460 Test the PDL before you push it to the main repository. If the code is
461 broken for you, then it is most likely broken for others and they won't
462 be happy to have their recent PDL fail to build! NOTE: git makes it
463 very easy to maintain a separate branch of development. [ TBD, provide
464 information on how ].
465
466 Then update the shared repository (at SF) with your changes
467
468 git push origin master
469
471 Q: 5.1 What is threading (is PDL a newsreader) ?
472 Unfortunately, in the context of PDL the term threading can have two
473 different (but related) meanings:
474
475 · When mentioned in the INSTALL directions and possibly during the
476 build process we have the usual computer science meaning of
477 multithreading in mind (useful mainly on multiprocessor machines or
478 clusters)
479
480 · PDL threading of operations on piddles (as mentioned in the
481 indexing docs) is the iteration of a basic operation over
482 appropriate subslices of piddles, e.g. the inner product " inner
483 $a, $b" of a (3) pdl $a and a (3,5,4) pdl $b results in a (5,4)
484 piddle where each value is the result of an inner product of the
485 (3) pdl with a (3) subslice of the (3,5,4) piddle. For details
486 check PDL::Indexing
487
488 PDL threading leads naturally to potentially parallel code which can
489 make use of multithreading on multiprocessor machines/networks; there
490 you have the connection between the two types of use of the term.
491
492 Q: 5.2 What is a piddle?
493 Well, PDL scalar variables (which are instances of a particular class
494 of perl objects, i.e. blessed thingies (see "man perlobj" )) are in
495 common PDL parlance often called piddles (for example, check the
496 mailing list archives). Err, clear? If not, simply use the term piddle
497 when you refer to a PDL variable (an instance of a PDL object as you
498 might remember) regardless of what actual data the PDL variable
499 contains.
500
502 Q: 6.1 What is perldl?
503 Sometimes perldl is used as a synonym for PDL. Strictly speaking,
504 however, the name perldl is reserved for the little shell that comes
505 with the PDL distribution and is supposed to be used for the
506 interactive prototyping of PDL scripts. For details check perldl.
507
508 Q: 6.2 How do I get online help for PDL?
509 Just type " help" (shortcut = "?") at the " perldl" prompt and proceed
510 from there. Another useful command is the " apropos" (shortcut = "??")
511 command. Also try the " demo" command in the perldl shell if you are
512 new to PDL.
513
515 Q: 6.3 I want to access the third element of a pdl but $a[2] doesn't
516 work ?!
517 See answer to the next question why the normal perl array syntax
518 doesn't work for pdls.
519
520 Q: 6.4 The docs say pdls are some kind of array. But why doesn't the
521 perl array syntax work with pdls then ?
522 Ok, you are right in a way. The docs say that pdls can be thought of
523 arrays. More specifically, it says ( PDL::Impatient ):
524
525 I find when using perlDL it is most useful to think of
526 standard perl @x variables as "lists" of generic
527 "things" and PDL variables like $x as
528 "arrays" which can be contained in lists or
529 hashes.
530
531 So, while pdls can be thought of as some kind of multi-dimensional
532 array they are not arrays in the perl sense. Rather, from the point of
533 view of perl they are some special class (which is currently
534 implemented as an opaque pointer to some stuff in memory) and therefore
535 need special functions (or 'methods' if you are using the OO version)
536 to access individual elements or a range of elements. The
537 functions/methods to check are " at" / " set" (see the section
538 'Sections' in PDL::Impatient ) or the powerful " slice" function and
539 friends (see PDL::Slices and PDL::Indexing ).
540
541 Finally, to confuse you completely, you can have perl arrays of pdls,
542 e.g. $spec[3] can refer to a pdl representing ,e.g, a spectrum, where
543 $spec[3] is the fourth element of the perl list (or array ;) @spec .
544 This may be confusing but is very useful !
545
546 Q: 6.5 How do I concatenate piddles?
547 Most people will try to form new piddles from old piddles using some
548 variation over the theme: " $a = pdl([$b, 0, 2])" , but this does not
549 work. The way to concatenate piddles is to use the function " cat" (see
550 also " append" and " glue"). Similarly you can split piddles using the
551 command " dog" .
552
553 Q: 6.6 Sometimes I am getting these strange results when using inplace
554 operations?
555 This question is related to the " inplace" function. From the
556 documentation (see PDL::Impatient):
557
558 Most functions, e.g. log(), return a result which is
559 a transformation of their argument. This makes for
560 good programming practice. However many operations can
561 be done "in-place" and this may be required when large
562 arrays are in use and memory is at a premium. For these
563 circumstances the operator inplace() is provided which
564 prevents the extra copy and allows the argument to be
565 modified. e.g.:
566
567
568
569 $x = log($array); # $array unaffected
570 log( inplace($bigarray) ); # $bigarray changed in situ
571
572 And also from the doc !!:
573
574 Obviously when used with some functions which can
575 not be applied in situ (e.g. convolve()) unexpected
576 effects may occur!
577
578 Check the list of PDL functions at the end of PDL.pod which points out
579 " inplace" -safe functions.
580
581 Q: 6.7 What is this strange usage of the string concatenation operator
582 " .=" in PDL scripts?
583 See next question on assignment in PDL.
584
585 Q: 6.8 Why are there two different kinds of assignment in PDL ?
586 This is caused by the fact that currently the assignment operator " ="
587 allows only restricted overloading. For some purposes of PDL it turned
588 out to be necessary to have more control over the overloading of an
589 assignment operator. Therefore, PDL peruses the operator " .=" for
590 certain types of assignments.
591
592 Q: 6.9 How do I set a set of values in a piddle?
593 With versions of Perl prior to 5.6.7 this has to be done using a
594 temporary variable.
595
596 perldl> $a = sequence(5); p $a
597 [0 1 2 3 4]
598 perldl> $tmp = $a->slice('1:2'); p $tmp;
599 [1 2]
600 perldl> $tmp .= pdl([5, 6]); # Note .= !!
601 perldl> p $a
602 [0 5 6 3 4]
603
604 This can also be made into one expression, which is often seen in PDL
605 code:
606
607 perldl> ($tmp = $a->slice('1:2')) .= pdl([5,6])
608 perldl> p $a
609 [0 5 6 3 4]
610
611 In Perl 5.6.7 and higher this assignment can be simplified using lvalue
612 subroutines:
613
614 perldl> $a->slice('1:2') .= pdl([5,6])
615 perldl> p $a
616 [0 5 6 3 4]
617
618 see PDL::Lvalue for more info.
619
620 Q: 6.10 Can I use a piddle in a conditional expression?
621 Yes you can, but not in the way you probably tried first. It is not
622 possible to use a piddle directly in a conditional expression since
623 this is usually poorly defined. Instead PDL has two very useful
624 functions: " any" and " all" . Use these to test if any or all elements
625 in a piddle fulfils some criterion:
626
627 perldl> $a=pdl ( 1, -2, 3);
628 perldl> print '$a has at least one element < 0' if (any $a < 0);
629 $a has at least one element < 0
630
631 perldl> print '$a is not positive definite' unless (all $a > 0);
632 $a is not positive definite
633
634 Q: 6.11 Logical operators and piddles - '||' and ' & & ' doesn't work!
635 It is a common problem that you try to make a mask array or something
636 similar using a construct such as
637
638 $mask = which($piddle > 1 && $piddle < 2);
639
640 This does not work! What you are looking for is the bitwise logical
641 operators '|' and '&' which work on an element-by-element basis. So it
642 is really very simple: Do not use logial operators on multi-element
643 piddles since that really doesn't make sense, instead write the example
644 as:
645
646 $mask = which($piddle > 1 & $piddle < 2);
647
648 which works correctly.
649
651 Q: 6.12 What is a null pdl ?
652 " null" is a special token for 'empty piddle'. A null pdl can be used
653 to flag to a PDL function that it should create an appropriately sized
654 and typed piddle. Null piddles can be used in places where a PDL
655 function expects an output or temporary argument. Output and
656 temporary arguments are flagged in the signature of a PDL function
657 with the " [o]" and " [t]" qualifiers (see next question if you don't
658 know what the signature of a PDL function is). For example, you can
659 invoke the " sumover" function as follows:
660
661 sumover $a, $b=null;
662
663 which is equivalent to
664
665 $b = sumover $a;
666
667 If this seems still a bit murky check PDL::Indexing and PDL::PP for
668 details about calling conventions, the signature and threading (see
669 also below).
670
671 Q: 6.13 What is the signature of a PDL function ?
672 The signature of a function is an important concept in PDL. Many (but
673 not all) PDL function have a signature which specifies the arguments
674 and their (minimal) dimensionality. As an example, look at the
675 signature of the " maximum" function:
676
677 'a(n); [o] b;'
678
679 this says that " maximum" takes two arguments, the first of which is
680 (at least) one-dimensional while the second one is zero-dimensional and
681 an output argument (flagged by the " [o]" qualifier). If the function
682 is called with pdls of higher dimension the function will be repeatedly
683 called with slices of these pdls of appropriate dimension(this is
684 called threading in PDL).
685
686 For details and further explanations consult PDL::Indexing and PDL::PP
687 .
688
689 Q: 6.14 How can I subclass (inherit from) piddles?
690 The short answer is: read PDL::Objects (e.g. type " help PDL::Objects"
691 in the perldl shell).
692
693 The longer answer (extracted from PDL::Objects ): Since a PDL object is
694 an opaque reference to a C struct, it is not possible to extend the PDL
695 class by e.g. extra data via subclassing (as you could do with a hash
696 based perl object). To circumvent this problem PDL has built-in
697 support to extent the PDL class via the has-a relation for blessed
698 hashes. You can get the HAS-A behave like IS-A simply in that you
699 assign the PDL object to the attribute named " PDL" and redefine the
700 method initialize(). For example:
701
702 package FOO;
703
704 @FOO::ISA = qw(PDL);
705 sub initialize {
706 my $class = shift;
707 my $self = {
708 creation_time => time(), # necessary extension :-)
709 PDL => PDL->null, # used to store PDL object
710 };
711 bless $self, $class;
712 }
713
714 For another example check the script t/subclass.t in the PDL
715 distribution.
716
717 Q: 6.15 What on earth is this dataflow stuff ?
718 Dataflow is an experimental project that you don't need to concern
719 yourself with (it should not interfere with your usual programming).
720 However, if you want to know, have a look at PDL::Dataflow . There are
721 applications which will benefit from this feature (and it is already at
722 work behind the scenes).
723
724 Q: 6.16 What is PDL::PP?
725 Simple answer: PDL::PP is both a glue between external libraries and
726 PDL and a concise language for writing PDL functions.
727
728 Slightly longer answer: PDL::PP is used to compile very concise
729 definitions into XSUB routines implemented in C that can easily be
730 called from PDL and which automatically support threading, dataflow and
731 other things without you having to worry about it.
732
733 For further details check PDL::PP and the section below on Extensions
734 of PDL.
735
736 Q: 6.17 What happens when I have several references to the same PDL
737 object in different variables (cloning, etc?) ?
738 Piddles behave like perl references in many respects. So when you say
739
740 $a = pdl [0,1,2,3];
741 $b = $a;
742
743 then both $b and $a point to the same object, e.g. then saying
744
745 $b++;
746
747 will *not* create a copy of the original piddle but just increment in
748 place, of which you can convince yourself by saying
749
750 print $a;
751 [1 2 3 4]
752
753 This should not be mistaken for dataflow which connects several
754 *different* objects so that data changes are propagated between the so
755 linked piddles (though, under certain circumstances, dataflown piddles
756 can share physically the same data).
757
758 It is important to keep the "reference nature" of piddles in mind when
759 passing piddles into subroutines. If you modify the input pdls you
760 modify the original argument, not a copy of it. This is different from
761 some other array processing languages but makes for very efficient
762 passing of piddles between subroutines. If you do not want to modify
763 the original argument but rather a copy of it just create a copy
764 explicitly (this example also demonstrates how to properly check for an
765 explicit request to process inplace, assuming your routine can work
766 inplace):
767
768 sub myfunc {
769 my $pdl = shift;
770 if ($pdl->is_inplace) {
771 $pdl->set_inplace(0)
772 } else {
773 # modify a copy by default
774 $pdl = $pdl->copy
775 }
776 $pdl->set(0,0);
777 return $pdl;
778 }
779
781 Q: 6.18 What I/O formats are supported by PDL ?
782 The current versions of PDL already support quite a number of different
783 I/O formats. However, it is not always obvious which module implements
784 which formats. To help you find the right module for the format you
785 require, here is a short list of the current list of I/O formats and a
786 hint in which module to find the implementation:
787
788 · A home brew fast raw (binary) I/O format for PDL is implemented by
789 the FastRaw module
790
791 · The FlexRaw module implements generic methods for the input and
792 output of `raw' data arrays. In particular, it is designed to read
793 output from FORTRAN 77 UNFORMATTED files and the low-level C write
794 function, even if the files are compressed or gzipped.
795
796 It is possible that the FastRaw functionality will be included in
797 the FlexRaw module at some time in the future.
798
799 · FITS I/O is implemented by the wfits/rfits functions in
800 PDL::IO::Misc.
801
802 · Ascii file I/O in various formats can be achieved by using the "
803 rcols" and " rgrep" functions, also in PDL::IO::Misc.
804
805 · PDL::IO::Pic implements an interface to the netpbm/pbm+ filters to
806 read/write several popular image formats; also supported is output
807 of image sequences as MPEG movies.
808
809 · On CPAN you can find the PDL-NetCDF module that works with the
810 current released version of PDL 2.4.3 [ What about 2.4.4? ].
811
812 For further details consult the documentation in the individual
813 modules.
814
815 Q: 6.19 How can I stack a set of 2D arrays (images) into a 3D piddle?
816 Assuming all arrays are of the same size and in some format recognised
817 by rpic (see PDL::IO::Pic ) you could say:
818
819 use PDL::IO::Pic;
820 @names = qw/name1.tif .... nameN.tif/; # some file names
821 $dummy = PDL->rpic($names[0]);
822 $cube = PDL->zeroes($dummy->type,$dummy->dims,$#names+1); # make 3D piddle
823 for (0..$#names) {
824 ($tmp = $cube->slice(":,:,($_)")) .= PDL->rpic($names[$_])
825 }
826
827 or
828
829 $cube(:,:,($_)) .= PDL->rpic($names[$_])
830
831 for the slice assignment using the new PDL::NiceSlice syntax and Lvalue
832 assignments.
833
834 The for loop reads the actual images into a temporary 2D piddle whose
835 values are then assigned (using the overloaded " .=" operator) to the
836 approriate slices of the 3D piddle $cube .
837
838 Q: 6.20 Where are testfiles for the graphics modules?
839 This answer applies mainly to PDL::Graphics::TriD (PDL's device
840 independent 3D graphics model) which is the trickiest one in this
841 respect. You find some test scripts in Demos/TriD in the distribution.
842 There are also "3dtest.pl" and "line3d.pl" in the PDL/Example/TriD
843 directory. After you have built PDL you can do:
844
845 perl -Mblib Example/TriD/3dtest.pl
846
847 perl -Mblib Example/TriD/line3d.pl
848
849 to try the two TriD test programs. They only exercise one TriD
850 function each but their simplicity makes it easy to debug if needed
851 with the perl debugger, see perldbug.
852
853 The programs in the Demo directory can be run most easily from the
854 "perldl" interactive shell:
855
856 perl -Mblib perldl
857
858 followed by " demo 3d" or " demo 3d2" at the prompt. " demo" by itself
859 will give you a list of the available PDL demos.
860
861 You can run the test scripts in the Demos/TriD directory manually by
862 changing to that directory and running
863
864 perl -Mblib <testfile>
865
866 where " < testfile "> ; should match the pattern " test[3-9].p" and
867 watch the results. Some of the tests should bring up a window where you
868 can control (twiddle) the 3D objects with the mouse. Try using MB1 for
869 turning the objects in 3D space, MB3 to zoom in and out, and 'q' to
870 advance to the next stage of the test.
871
872 Q: 6.21 What is TriD or PDL::TriD or PDL::Graphics::TriD?
873 Questions like this should be a thing of the past with the PDL online
874 help system in place. Just try (after installation):
875
876 un*x> perldl
877 perldl> apropos trid
878
879 Check the output for promising hits and then try to look up some of
880 them, e.g.
881
882 perldl> help PDL::Graphics::TriD
883
884 Note that case matters with " help" but not with " apropos" .
885
886 Q: 6.22 PGPLOT does not write out PNG files.
887 There are a few sources of trouble with PGPLOT and PNG files. First,
888 when compiling the pgplot libraries, make sure you uncommented the PNG
889 entries in the drivers.list file. Then when running 'make' you probably
890 got an error like
891
892 "make: *** No rule to make target `png.h', needed by `pndriv.o'.
893 Stop."
894
895 To fix this, find the line in the 'makefile' that starts with
896 'pndriv.o:' (it's near the bottom). Change, for example, ./png.h to
897 /usr/include/png.h, if that is where your header files are (you do have
898 the libpng and libz devel packages, don't you?). Do this for all four
899 entries on that line, then go back and run "make".
900
901 Second, if you already have the PGPLOT Perl module and PDL installed,
902 you probably tried to write out a png file and got fatal error message
903 like:
904
905 "undefined symbol: png_create_write_struct"
906
907 This is because the PGPLOT perl module does not automatically link
908 against the png and z libraries. So when you are installing the PGPLOT
909 perl module (version 2.19) from CPAN, don't do "install PGPLOT", but
910 just do "get PGPLOT". Then exit from CPAN and manually install PGPLOT,
911 calling the makefile thusly:
912
913 "perl Makefile.PL EXLIB=png,z EXDIR=/usr/lib"
914
915 assuming that there exist files such as /usr/lib/libpng.so.*,
916 /usr/lib/libz.so.*. Then do the standard "make;make test;make install;"
917 sequence. Now you can write png files from PDL!
918
920 Q: 7.1 I am looking for a package to do XXX in PDL. Where shall I look
921 for it?
922 The first stop is again " perldl" or the PDL documentation. There is
923 already a lot of functionality in PDL which you might be aware of. The
924 easiest way to look for functionality is to use the " apropos" command:
925
926 perldl> apropos 'integral'
927 ceil Round to integral values in floating-point format
928 floor Round to integral values in floating-point format
929 intover Project via integral to N-1 dimensions
930 rint Round to integral values in floating-point format
931
932 Since the apropos command is no sophisticated search engine make sure
933 that you search on a couple of related topics and use short phrases.
934
935 However there is a good chance that what you need is not part of the
936 PDL distribution. You are then well advised to check out
937 http://pdl.perl.org where there is a list of packages using PDL. If
938 that does not solve your problem, ask on the mailing-list, if nothing
939 else you might get assistance which will let you interface your package
940 with PDL yourself, see also the next question.
941
942 Q: 7.2 Can I access my C/Fortran library routines in PDL?
943 Yes, you can, in fact it is very simple for many simple applications.
944 What you want is the PDL pre-prosessor PP (PDL::PP ). This will allow
945 you to make a simple interface to your C routine.
946
947 The two functions you need to learn (at least first) are " pp_def"
948 which defines the calling interface to the function, specifying input
949 and output parameters, and contains the code that links to the external
950 library. The other command is " pp_end" which finishes the PP
951 definitions. For details see the PDL::PP man-page, but we also have a
952 worked example here.
953
954 double eight_sum(int n)
955 {
956 int i;
957 double sum, x;
958
959 sum = 0.0; x=0.0;
960 for (i=1; i<=n; i++) {
961 x++;
962 sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
963 }
964 return 1.0/sum;
965 }
966
967 We will here show you an example of how you interface C code with PDL.
968 This is the first example and will show you how to approximate the
969 number 8...
970
971 The C code is shown above and is a simple function returning a double,
972 and expecting an integer - the number of terms in the sum - as input.
973 This function could be defined in a library or, as we do here, as an
974 inline function.
975
976 We will postpone the writing of the Makefile till later. First we will
977 construct the " .pd" file. This is the file containing PDL::PP code. We
978 call this " eight.pd" .
979
980 #
981 # pp_def defines a PDL function.
982 #
983 pp_addhdr (
984 '
985 double eight_sum(int n)
986 {
987 int i;
988 double sum, x;
989
990 sum = 0.0; x=0.0;
991 for (i=1; i<=n; i++) {
992 x++;
993 sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
994 }
995 return 1.0/sum;
996
997 }
998 ');
999
1000
1001
1002 pp_def (
1003 'eight',
1004 Pars => 'int a(); double [o]b();',
1005 Code => '$b()=eight_sum($a());'
1006 );
1007
1008 # Always make sure that you finish your PP declarations with
1009 # pp_done
1010
1011 pp_done();
1012
1013 A peculiarity with our example is that we have included the entire code
1014 with " pp_addhdr" instead of linking it in. This is only for the
1015 purposes of example, in a typical application you will use " pp_addhdr"
1016 to include header files. Note that the argument to " pp_addhdr" is
1017 enclosed in quotes.
1018
1019 What is most important in this example is however the " pp_def"
1020 command. The first argument to this is the name of the new function
1021 eight , then comes a hash which the real meat:
1022
1023 · This gives the input parameters (here " a" ) and the output
1024 parameters (here " b" ). The latter are indicated by the " [o]"
1025 specifier. Both arguments can have a type specification as shown
1026 here.
1027
1028 Many variations and further flexibility in the interface can be
1029 specified. See the manpage for details.
1030
1031 · This switch contains the code that should be executed. As you can
1032 see this is a rather peculiar mix of C and Perl, but essentially it
1033 is just as you would write it in C, but the variables that are
1034 passed from PDL are treated differently and have to be referred to
1035 with a preceding '$'.
1036
1037 There are also simple macros to pass pointers to data and to obtain
1038 the values of other Perl quantities, see the manual page for
1039 further details.
1040
1041 Finally note the call to " pp_done()" at the end of the file. This is
1042 necessary in all PP files.
1043
1044 Ok. So now we have a file with code that we dearly would like to use in
1045 Perl via PDL. To do this we need to compile the function, and to do
1046 that we need a Makefile.
1047
1048 use PDL::Core::Dev;
1049 use ExtUtils::MakeMaker;
1050 PDL::Core::Dev->import();
1051
1052 $package = ["eight.pd",Eight,PDL::Eight];
1053 %hash = pdlpp_stdargs($package);
1054
1055 WriteMakefile( %hash );
1056
1057 sub MY::postamble {pdlpp_postamble($package)};
1058
1059 The code above should go in a file called Makefile.PL, which should
1060 subsequently be called in the standard Perl way: " perl Makefile.PL" .
1061 This should give you a Makefile and running " make" should compile the
1062 module for you and " make install" will install it for you.
1063
1064 Q: 7.3 How can I interface package XXX in PDL?
1065 This question is closely related to the previous one, and as we said
1066 there, the PDL::PP pre-processor is the standard way of interfacing
1067 external packages with PDL. The most usual way to use PDL::PP is to
1068 write a short interface routine, see the PDL::PP manpage and the answer
1069 to the previous question for examples.
1070
1071 However it is also possible to interface a package to PDL by re-writing
1072 your function in PDL::PP directly. This can be convenient in certain
1073 situations, in particular if you have a routine that expects a function
1074 as input and you would like to pass the function a Perl function for
1075 convenience.
1076
1077 The PDL::PP manpage is the main source of information for writing
1078 PDL::PP extensions, but it is very useful to look for files in the
1079 distribution of PDL as many of the core functions are written in
1080 PDL::PP. Look for files that end in " .pd" which is the generally
1081 accepted suffix for PDL::PP files. But we also have a simple example
1082 here.
1083
1084 The following example will show you how to write a simple function that
1085 automatically allows threading. To make this concise the example is of
1086 an almost trivial function, but the intention is to show the basics of
1087 writing a PDL::PP interface.
1088
1089 We will write a simple function that calculates the minimum, maximum
1090 and average of a piddle. On my machine the resulting function is 8
1091 times faster than the built-in function " stats" (of course the latter
1092 also calculates the median).
1093
1094 Let's jump straight in. Here is the code (from a file called "
1095 quickstats.pd" )
1096
1097 #
1098 pp_def('quickstats',
1099 Pars => 'a(n); [o]avg(); [o]max(); [o]min()',
1100 Code => '$GENERIC(a) curmax, curmin;
1101 $GENERIC(a) tmp=0;
1102 loop(n) %{
1103 tmp += $a();
1104 if (!n || $a() > curmax) { curmax = $a();}
1105 if (!n || $a() < curmin) { curmin = $a();}
1106 %}
1107 $avg() = tmp/$SIZE(n);
1108 $max() = curmax;
1109 $min() = curmin;
1110 '
1111 );
1112
1113 pp_done();
1114
1115 The above might look like a confusing mixture of C and Perl, but behind
1116 the peculiar syntax lies a very powerful language. Let us take it line
1117 by line.
1118
1119 The first line declares that we are starting the definition of a PDL:PP
1120 function called " quickstats" .
1121
1122 The second line is very important as it specifies the input and output
1123 parameters of the function. a(n) tells us that there is one input
1124 parameter that we will refer to as " a" which is expected to be a
1125 vector of length n (likewise matrices, both square and rectangular
1126 would be written as " a(n,n)" and " a(n,m)" respectively). To indicate
1127 that something is an output parameter we put " [o]" in front of their
1128 names, so referring back to the code we see that avg, max and min are
1129 three output parameters, all of which are scalar (since they have no
1130 dimensional size indicated.
1131
1132 The third line starts the code definition which is essentially pure C
1133 but with a couple of convenient functions. $GENERIC is a function
1134 that returns the C type of its argument - here the input parameter a.
1135 Thus the first two lines of the code section are variable declarations.
1136
1137 The loop(n) construct is a convenience function that loops over the
1138 dimension called n in the parameter section. Inside this loop we
1139 calculate the cumulative sum of the input vector and keep track of the
1140 maximum and minimum values. Finally we assign the resulting values to
1141 the output parameters.
1142
1143 Finally we finish our function declaration with " pp_done()" .
1144
1145 To compile our new function we need to create a Makefile, which we will
1146 just list since its creation is discussed in an earlier question.
1147
1148 use PDL::Core::Dev;
1149 use ExtUtils::MakeMaker;
1150 PDL::Core::Dev->import();
1151
1152 $package = ["quickstats.pd",Quickstats,PDL::Quickstats];
1153 %hash = pdlpp_stdargs($package);
1154
1155 WriteMakefile( %hash );
1156
1157 sub MY::postamble {pdlpp_postamble($package)};
1158
1159 An example Makefile.PL
1160
1161 Our new statistic function should now compile using the tried and
1162 tested perl way: " perl Makefile.PL; make" .
1163
1164 You should experiment with this function, changing the calculations and
1165 input and output parameters. In conjunction with the PDL::PP manpage
1166 this should allow you to quickly write more advanced routines directly
1167 in PDL::PP.
1168
1171 ·
1172
1173
1174 · General minor update: mailing list info, links, version, date,
1175 some text.
1176
1177 · Removed FAQ maintainer.
1178
1179 ·
1180
1181
1182 · markers for alpha stage functionality removed
1183
1184 · restructured description
1185
1186 · development/support of PDL
1187
1188 · PDL and online help
1189
1190 · subclassing piddles
1191
1192 · new INSTALLATION section
1193
1194 · how to stack 2D piddles - > 3D piddle
1195
1196 · questions regarding TriD
1197
1198 ·
1199
1200
1201 · use of perl 5.6.2 (a.k.a. perl 5.006002) is now required
1202
1203 · PDL I/O formats
1204
1205 · piddles behave like perl references
1206
1207 · null PDL's and output arguments
1208
1209 · signature
1210
1211 ·
1212
1213
1214 · questions about pdls and perl array syntax
1215
1216 · added requirement for C compiler in answer to 'what
1217 machines...' question
1218
1219 · PDL jargon section
1220
1221 · piddles
1222
1223 ·
1224
1225
1226 · upgraded released/alpha version numbers
1227
1228 · added another WYANDL reason
1229
1230 · split into perldl/pdl-porters mailing lists
1231
1232 ·
1233
1234
1235 · initial revision
1236
1238 If you find any inaccuracies in this document (or disfunctional URLs)
1239 please report to the perldl mailing list perldl@jach.hawaii.edu.
1240
1242 Achim Bohnet (ach@mpe.mpg.de ) for suggesting CoolHTML as a
1243 prettypodder (although we have switched to XML now) and various other
1244 improvements. Suggestions for some questions were taken from Perl Faq
1245 and adapted for PDL.
1246
1248 Many people have contributed or given feedback on the current version
1249 of the FAQ, here is an incomplete list of individuals whose
1250 contributions or posts to the mailing-list have improved this FAQ at
1251 some point in time alphabetically listed by first name: Christian
1252 Soeller, Doug Burke, Doug Hunt, Frank Schmauder, Jarle Brinchmann, John
1253 Cerney, Karl Glazebrook, Kurt Starsinic, Thomas Yengst, Tuomas J.
1254 Lukka.
1255
1257 This document emerged from a joint effort of several PDL developers
1258 (Karl Glazebrook, Tuomas J. Lukka, Christian Soeller) to compile a list
1259 of the most frequently asked questions about PDL with answers.
1260 Permission is granted for verbatim copying (and formatting) of this
1261 material as part of PDL.
1262
1263 Permission is explicitly not granted for distribution in book or any
1264 corresponding form. Ask on the PDL mailing list perldl@jach.hawaii.edu
1265 if some of the issues covered in here are unclear.
1266
1267
1268
1269perl v5.12.3 2009-12-29 FAQ(1)