1COURSE(1) User Contributed Perl Documentation COURSE(1)
2
6 PDL::Course - A journey through PDL's documentation, from beginner to
7 advanced.
8
10 This is written by David Mertens with edits by Daniel Carrera.
11
13 PDL's documentation is extensive. Some sections cover deep core magic
14 while others cover more usual topics like IO and numerical computation.
15 How are these related? Where should you begin?
16 This document is an attempt to pull all the key PDL documentation
18 together in a coherent study course, starting from the beginner level,
19 up to the expert.
20 I've broken down everything by level of expertise, and within expertise
22 I've covered documentation, library, and workflow modules. The
23 documentation modules are useful for what they tell you; the library
24 modules are useful for the functions that they define for you; the
25 workflow modules are useful for the way that they allow you to get your
26 work done in new and different ways.
27
29 If you are new to PDL, these documentation modules will get you started
30 down the right path for using PDL.
31 Documentation
33 Modules that tell you how to start using PDL. Many of these are
34 library modules technically, but they are included when you "use PDL",
35 so I've included them for their documentation.
36 After the first three, most of the docs listed below are rather dry.
38 Perhaps they would be better summarized by tables or better synopses.
39 You should at least scan through them to familiarize yourself with the
40 basic capabilities of PDL.
41 • PDL::Philosophy, PDL::QuickStart
43 A couple of brief introductions to PDL. The second one is a bit
45 more hands-on. If you are new to PDL, you should start with these.
46 • PDL::Basic
48 Covers basic piddle-creation routines like "sequence", "rvals", and
50 "logxvals" to name a random few. Also covers "hist" and
51 "transpose".
52 • PDL::Ufunc
54 Explains a large collection of built-in functions which, given an
56 N-dimension piddle, will create a piddle with N-1 dimensions.
57 • PDL::NiceSlice
59 PDL came of age right around the turn of the millennium and
61 NiceSlice came on the scene slightly after that. Some of the docs
62 still haven't caught up. NiceSlice is the 'modern' way to slice
63 and dice your piddles. Read the Synopsis, then scroll down to The
64 New Slicing Syntax. After you've read to the bottom, return to and
65 read the stuff at the top.
66 • PDL::Primitive
68 Defines a whole slew of useful built-in functions. These are the
70 sorts of things that beginners are likely to write to the list and
71 say, "How do I do xxx?" You would be well on your way to learning
72 the ropes after you've gotten through this document.
73 • Selections from PDL::Core
75 Like PDL::Primitive, defines a large set of useful functions.
77 Unfortunately, some of the functions are quite esoteric, but are
78 mixed in with the rest of the simple and easy ones. Skim the whole
79 document, skipping over the complicated functions for now. I would
80 point out in particular the function "approx".
81 Workflow
83 • The perldl or pdl2 Shell
84 The Perldl Shell is a REPL (Read-Evaluate-Print-Loop, in other
86 words, a prompt or shell) that allows you to work with PDL (or any
87 Perl, for that matter) in 'real time', loading data from files,
88 plotting, manipulating... Anything you can do in a script, you can
89 do in the PDL Shell, with instant feedback!
90 Libraries
92 • PDL
93 The main workhorse module. You'll include this in nearly every PDL
95 program you write.
96
98 The sorts of modules that you'll likely use on a normal basis in
99 scripts or from within the perldl shell. Some of these modules you may
100 never use, but you should still be aware that they exist, just in case
101 you need their functionality.
102 Documentation
104 • PDL::Slices
105 In addition to explaining the original slicing and dicing functions
107 - for which you can usually use PDL::NiceSlice - this also covers
108 many dimension-handling functions such as "mv", "xchg", and
109 "reorder". This also thoroughly documents the "range" function,
110 which can be very powerful, and covers a number of internal
111 functions, which can probably be skipped.
112 • PDL::Indexing
114 This covers a lot of the deeper conceptual ground that you'll need
116 to grasp to really use PDL to its full potential. It gets more
117 complex as you go along, so don't be troubled if you find yourself
118 loosing interest half way through. However, reading this document
119 all the way through will bring you much closer to PDL
120 enlightenment.
121 • PDL::IO
123 PDL has quite a few IO modules, most of which are discussed in this
125 summary module.
126 • PDL::Tips
128 A collection of some of Tuomas's ideas for making good use of PDL.
130 • PDL::BadValues
132 Explains what bad values are and how and why they are implemented.
134 • Selections from Inline::Pdlpp
136 Although writing PDL::PP code is considered an Advanced topic, and
138 is covered in the next section, you should be aware that it is
139 possible (and surprisingly simple) to write PDL-aware code. You
140 needn't read the whole thing at this point, but to get some feel
141 for how it works, you should read everything up through the first
142 example. A copy of this documentation is contained in
143 PDL::PP-Inline.
144 • PDL::Objects
146 Explains how to subclass a piddle object.
148 • PDL::Index
150 This was discussed in the Preface. It is an automatically generated
152 file that lists all of the PDL modules on your computer. There are
153 many modules that may be on your machine but which are not
154 documented here, such as bindings to the FFTW library, or GSL. Give
155 it a read!
156 Libraries
158 • PDL::Complex
159 Complex number support. No, PDL does not have complex number
161 support built into the core, but this should help you out.
162 • PDL::FFT
164 PDL's own Fast Fourier Transform. If you have FFTW, then you
166 should probably make use of it; this is PDL's internal
167 implementation and should always be available.
168 • GSL
170 PDL does not have bindings for every sub-library in the GNU
172 Scientific Library, but it has quite a few. If you have GSL
173 installed on your machine then chances are decent that your PDL has
174 the GSL bindings. For a full list of the GSL bindings, check
175 PDL::Index.
176 • PDL::Func
178 A somewhat uniform interface to the different interpolation modules
180 in PDL.
181 • PDL::Bad
183 Includes some basic bad-value functionality, including functions to
185 query if a piddle has bad values ("isbad") and functions to set
186 certain elements as bad ("setbadat" and "setbadif"). Among other
187 places, bad values are used in PDL::Graphics::PLplot's xyplot to
188 make a gap in a line plot.
189 • PDL::DiskCache
191 A cool module that allows you to tie a Perl array to a collection
193 of files on your disk, which will be loaded into and out of memory
194 as piddles. If you find yourself writing scripts to process many
195 data files, especially if that data processing is not necessarily
196 in sequential order, you should consider using PDL::DiskCache.
197 • PDL::Char
199 A PDL subclass that allows you to store and manipulate collections
201 of fixed-length character strings using PDL.
202 • PDL::Image2D
204 A whole collection of methods for manipulating images whose image
206 data are stored in a piddle. These include methods for
207 convolutions (smoothing), polygon fills, scaling, rotation, and
208 warping, among others.
209 • PDL::ImageND
211 Contains a few functions that are conceptually related to image
213 processing, but which can be defined for higher-dimensional data.
214 For examples this module defines high-dimensional convolution and
215 interpolation, among others.
216 • PDL::ImageRGB
218 Defines some useful functions for working with RBG image data.
220 It's not very feature-full, but it may have something you need, and
221 if not, you can always add more!
222 • PDL::Transform
224 Creates the transform class, which allows you to create various
226 coordinate transforms. For example, if you data is a collection of
227 Cartesian coordinates, you could create a transform object to
228 convert them to Spherical-Polar coordinates (although many such
229 standard coordinate transformations are predefined for you, in this
230 case it's called "t_spherical").
231 • PDL::Opt::Simplex
233 This package states that it "implements the commonly used simplex
235 optimization algorithm." I'm going to assume that if you need this
236 algorithm then you already know what it is.
237 • PDL::Math
239 A collection of fairly standard math functions, like the inverse
241 trigonometric functions, hyperbolic functions and their inverses,
242 and others. This module is included in the standard call to "use
243 PDL", but not in the Lite versions.
244 • PDL::Matrix
246 Provides a few functions that use the standard mathematical Matrix
248 notation of row-column indexing rather than the PDL-standard
249 column-row. It appears that this module has not been heavily
250 tested with other modules, so although it should work with other
251 modules, don't be surprised if something breaks when you use it
252 (and feel free to offer any fixes that you may develop).
253 • PDL::MatrixOps
255 Provides many standard matrix operations for piddles, such as
257 computing eigenvalues, inverting square matrices, LU-decomposition,
258 and solving a system of linear equations. Though it is not built
259 on PDL::Matrix, it should generally work with that module. Also,
260 the methods provided by this module do not depend on external
261 libraries such as Slatec or GSL.
262 • PDL::Reduce
264 Implements an interface to all the functions that return piddles
266 with one less dimension (for example, "sumover"), such that they
267 can be called by suppling their name, as a string.
268 Workflow
270 • PDL::AutoLoader
271 Enables Matlab-style autoloading. When you call an unknown
273 function, instead of complaining and croaking, PDL will go hunt
274 around in the directories you specify in search of a like-named
275 file. Particularly useful when used with the Perldl Shell.
276 • PDL::Dbg
278 Declares the "px" function, which can be handy for debugging your
280 PDL scripts and/or perldl shell commands.
281 • PDL::Options
283 Suppose you define a powerful, versatile function. Chances are
285 good that you'll accept the arguments in the form of a hash or
286 hashref. Now you face the problem of processing that hashref.
287 PDL::Options assists you in writing code to process those options.
288 (You'd think Perl would have tons of these sorts of modules lying
289 around, but I couldn't find any.) Note this module does not depend
290 on PDL for its usage or installation.
291 • PDL::pdldoc
293 Ever fired-up the perldl shell just to look up the help for a
295 particular function? You can use "pdldoc" instead. This shell
296 script extracts information from the help index without needing to
297 start the perldl shell.
298
300 The sorts of modules and documentation that you'll use if you write
301 modules that use PDL, or if you work on PDL maintenance. These modules
302 can be difficult to use, but enable you to tackle some of your harder
303 problems.
304 • PDL::Lite, PDL::LiteF
306 Lite-weight replacements for "use PDL", from the standpoint of
308 namespace pollution and load time.
309 • Inline::Pdlpp
311 This was mentioned earlier. Before you begin reading about PDL::PP
313 (next), you should remind yourself about how to use this.
314 Inline::Pdlpp will help you experiment with PDL::PP without having
315 to go through the trouble of building a module and constructing
316 makefiles (but see PDL::pptemplate for help on that).
317 • PDL::PP
319 The PDL Pre-Processor, which vastly simplifies making you C or
321 Fortran code play with Perl and piddles. Most of PDL's basic
322 functionality is written using PDL::PP, so if you're thinking about
323 how you might integrate some numerical library written in C, look
324 no further.
325 • PDL::pptemplate
327 A script that automates the creation of modules that use PDL::PP,
329 which should make your life as a module author a bit simpler.
330 • PDL::CallExt
332 Allows you to call functions using external shared libraries. This
334 is an alternative to using PDL::PP. The major difference between
335 PDL::PP and PDL::CallExt is that the former will handle threading
336 over implicit thread dimensions for you, whereas PDL::CallExt
337 simply calls an external function. PDL::PP is generally the
338 recommended way to interface your code with PDL, but it wouldn't be
339 Perl if there wasn't another way to do it.
340 • PDL::Config
342 Defines the %PDL::Config hash, which has lots of useful information
344 pertinent to your PDL build.
345 • PDL::Doc
347 Explanation of the PDL documentation conventions, and an interface
349 to the PDL Documentation parser. Following these guidelines when
350 writing documentation for PDL functions will ensure that your
351 wonderful documentation is accessible from the perldl shell and
352 from calls to "barf". (Did you notice that "barf" used your
353 documentation? Time to reread PDL::Core...)
354 • PDL::Exporter
356 A simple replacement for the standard Exporter module. The only
358 major difference is that the default imported modules are those
359 marked ':Func'.
360 • PDL::Types
362 Defines some useful functions for getting a piddle's type, as well
364 as getting information about that type.
365 • PDL::Version
367 Simply defines the scalar $PDL::Version::Version with the current
369 version of PDL, as defined in PDL.pm. This is most useful if you
370 distribute your own module on CPAN, use PDL::Lite or PDL::LiteF and
371 want to make sure that your users have a recent-enough version of
372 PDL. Since the variable is defined in PDL.pm, you don't need this
373 module if you "use PDL".
374
376 • PDL::Core::Dev
377 Provides some decently useful functions that are pretty much only
379 needed by the PDL Porters.
380 • PDL::API
382 Explains how to make a piddle by hand, from Perl or your C source
384 code, using the PDL API.
385 • PDL::Internals
387 Explains the nitty-gritty of the PDL data structures. After
389 reading this (a few times :), you should be able to create a piddle
390 completely from scratch (i.e. without using the PDL API). Put a
391 little differently, if you want to understand how PDL::PP works,
392 you'll need to read this.
393
395 Copyright 2010 David Mertens (dcmertens.perl@gmail.com). You can
396 distribute and/or modify this document under the same terms as the
397 current Perl license.
398 See: http://dev.perl.org/licenses/
400perl v5.32.1 2021-02-15 COURSE(1)