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