1COURSE(1)             User Contributed Perl Documentation            COURSE(1)
2
3
4

NAME

6       PDL::Course - A journey through PDL's documentation, from beginner to
7       advanced.
8

AUTHOR, DATE

10       This is written by David Mertens with edits by Daniel Carrera.
11

Preface

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
17       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
21       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

Introductory

29       If you are new to PDL, these documentation modules will get you started
30       down the right path for using PDL.
31
32   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
37       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
42       •   PDL::Philosophy, PDL::QuickStart
43
44           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
47       •   PDL::Basic
48
49           Covers basic piddle-creation routines like "sequence", "rvals", and
50           "logxvals" to name a random few.  Also covers "hist" and
51           "transpose".
52
53       •   PDL::Ufunc
54
55           Explains a large collection of built-in functions which, given an
56           N-dimension piddle, will create a piddle with N-1 dimensions.
57
58       •   PDL::NiceSlice
59
60           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
67       •   PDL::Primitive
68
69           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
74       •   Selections from PDL::Core
75
76           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
82   Workflow
83       •   The perldl or pdl2 Shell
84
85           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
91   Libraries
92       •   PDL
93
94           The main workhorse module. You'll include this in nearly every PDL
95           program you write.
96

Normal Usage

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
103   Documentation
104       •   PDL::Slices
105
106           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
113       •   PDL::Indexing
114
115           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
122       •   PDL::IO
123
124           PDL has quite a few IO modules, most of which are discussed in this
125           summary module.
126
127       •   PDL::Tips
128
129           A collection of some of Tuomas's ideas for making good use of PDL.
130
131       •   PDL::BadValues
132
133           Explains what bad values are and how and why they are implemented.
134
135       •   Selections from Inline::Pdlpp
136
137           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
145       •   PDL::Objects
146
147           Explains how to subclass a piddle object.
148
149       •   PDL::Index
150
151           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
157   Libraries
158       •   PDL::Complex
159
160           Complex number support.  No, PDL does not have complex number
161           support built into the core, but this should help you out.
162
163       •   PDL::FFT
164
165           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
169       •   GSL
170
171           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
177       •   PDL::Func
178
179           A somewhat uniform interface to the different interpolation modules
180           in PDL.
181
182       •   PDL::Bad
183
184           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
190       •   PDL::DiskCache
191
192           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
198       •   PDL::Char
199
200           A PDL subclass that allows you to store and manipulate collections
201           of fixed-length character strings using PDL.
202
203       •   PDL::Image2D
204
205           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
210       •   PDL::ImageND
211
212           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
217       •   PDL::ImageRGB
218
219           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
223       •   PDL::Transform
224
225           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
232       •   PDL::Opt::Simplex
233
234           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
238       •   PDL::Math
239
240           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
245       •   PDL::Matrix
246
247           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
254       •   PDL::MatrixOps
255
256           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
263       •   PDL::Reduce
264
265           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
269   Workflow
270       •   PDL::AutoLoader
271
272           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
277       •   PDL::Dbg
278
279           Declares the "px" function, which can be handy for debugging your
280           PDL scripts and/or perldl shell commands.
281
282       •   PDL::Options
283
284           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
292       •   PDL::pdldoc
293
294           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

Advanced Usage

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
305       •   PDL::Lite, PDL::LiteF
306
307           Lite-weight replacements for "use PDL", from the standpoint of
308           namespace pollution and load time.
309
310       •   Inline::Pdlpp
311
312           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
318       •   PDL::PP
319
320           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
326       •   PDL::pptemplate
327
328           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
331       •   PDL::CallExt
332
333           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
341       •   PDL::Config
342
343           Defines the %PDL::Config hash, which has lots of useful information
344           pertinent to your PDL build.
345
346       •   PDL::Doc
347
348           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
355       •   PDL::Exporter
356
357           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
361       •   PDL::Types
362
363           Defines some useful functions for getting a piddle's type, as well
364           as getting information about that type.
365
366       •   PDL::Version
367
368           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

Expert Usage

376       •   PDL::Core::Dev
377
378           Provides some decently useful functions that are pretty much only
379           needed by the PDL Porters.
380
381       •   PDL::API
382
383           Explains how to make a piddle by hand, from Perl or your C source
384           code, using the PDL API.
385
386       •   PDL::Internals
387
388           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
399       See: http://dev.perl.org/licenses/
400
401
402
403perl v5.32.1                      2021-02-15                         COURSE(1)
Impressum