||User Contributed Perl Documentation
PDL::Course - A journey through PDL's documentation, from beginner to advanced.
This is written by David Mertens with edits by Daniel Carrera.
PDL's documentation is extensive. Some sections cover deep core magic while
others cover more usual topics like IO and numerical computation. How are
these related? Where should you begin?
This document is an attempt to pull all the key PDL documentation
together in a coherent study course, starting from the beginner level, up to
I've broken down everything by level of expertise, and within
expertise I've covered documentation, library, and workflow modules. The
documentation modules are useful for what they tell you; the library modules
are useful for the functions that they define for you; the workflow modules
are useful for the way that they allow you to get your work done in new and
If you are new to PDL, these documentation modules will get you started down the
right path for using PDL.
Modules that tell you how to start using PDL. Many of these are library modules
technically, but they are included when you "use
PDL", so I've included them for their documentation.
After the first three, most of the docs listed below are rather
dry. Perhaps they would be better summarized by tables or better synopses.
You should at least scan through them to familiarize yourself with the basic
capabilities of PDL.
- PDL::Philosophy, PDL::QuickStart
A couple of brief introductions to PDL. The second one is a
bit more hands-on. If you are new to PDL, you should start with
Covers basic piddle-creation routines like
"logxvals" to name a random few. Also
covers "hist" and
Explains a large collection of built-in functions which, given
an N-dimension piddle, will create a piddle with N-1 dimensions.
PDL came of age right around the turn of the millennium and
NiceSlice came on the scene slightly after that. Some of the docs still
haven't caught up. NiceSlice is the 'modern' way to slice and dice your
piddles. Read the Synopsis, then scroll down to The New Slicing Syntax.
After you've read to the bottom, return to and read the stuff at the
Defines a whole slew of useful built-in functions. These are
the sorts of things that beginners are likely to write to the list and
say, "How do I do xxx?" You would be well on your way to
learning the ropes after you've gotten through this document.
- Selections from PDL::Core
Like PDL::Primitive, defines a large set of useful functions.
Unfortunately, some of the functions are quite esoteric, but are mixed
in with the rest of the simple and easy ones. Skim the whole document,
skipping over the complicated functions for now. I would point out in
particular the function "approx".
- The perldl or pdl2 Shell
The Perldl Shell is a REPL (Read-Evaluate-Print-Loop, in other
words, a prompt or shell) that allows you to work with PDL (or any Perl,
for that matter) in 'real time', loading data from files, plotting,
manipulating... Anything you can do in a script, you can do in the PDL
Shell, with instant feedback!
The sorts of modules that you'll likely use on a normal basis in scripts or from
within the perldl shell. Some of these modules you may never use, but you
should still be aware that they exist, just in case you need their
The main workhorse module. You'll include this in nearly every
PDL program you write.
In addition to explaining the original slicing and dicing
functions - for which you can usually use PDL::NiceSlice - this also
covers many dimension-handling functions such as
"reorder". This also thoroughly
documents the "range" function, which
can be very powerful, and covers a number of internal functions, which
can probably be skipped.
This covers a lot of the deeper conceptual ground that you'll
need to grasp to really use PDL to its full potential. It gets more
complex as you go along, so don't be troubled if you find yourself
loosing interest half way through. However, reading this document all
the way through will bring you much closer to PDL enlightenment.
PDL has quite a few IO modules, most of which are discussed in
this summary module.
A collection of some of Tuomas's ideas for making good use of
Explains what bad values are and how and why they are
- Selections from Inline::Pdlpp
Although writing PDL::PP code is considered an Advanced topic,
and is covered in the next section, you should be aware that it is
possible (and surprisingly simple) to write PDL-aware code. You needn't
read the whole thing at this point, but to get some feel for how it
works, you should read everything up through the first example. A copy
of this documentation is contained in PDL::PP-Inline.
Explains how to subclass a piddle object.
This was discussed in the Preface. It is an automatically
generated file that lists all of the PDL modules on your computer. There
are many modules that may be on your machine but which are not
documented here, such as bindings to the FFTW library, or GSL. Give it a
Complex number support. No, PDL does not have complex number
support built into the core, but this should help you out.
PDL's own Fast Fourier Transform. If you have FFTW, then you
should probably make use of it; this is PDL's internal implementation
and should always be available.
PDL does not have bindings for every sub-library in the GNU
Scientific Library, but it has quite a few. If you have GSL installed on
your machine then chances are decent that your PDL has the GSL bindings.
For a full list of the GSL bindings, check PDL::Index.
A somewhat uniform interface to the different interpolation
modules in PDL.
Includes some basic bad-value functionality, including
functions to query if a piddle has bad values
("isbad") and functions to set certain
elements as bad ("setbadat" and
"setbadif"). Among other places, bad
values are used in PDL::Graphics::PLplot's xyplot to make a gap in a
A cool module that allows you to tie a Perl array to a
collection of files on your disk, which will be loaded into and out of
memory as piddles. If you find yourself writing scripts to process many
data files, especially if that data processing is not necessarily in
sequential order, you should consider using PDL::DiskCache.
A PDL subclass that allows you to store and manipulate
collections of fixed-length character strings using PDL.
A whole collection of methods for manipulating images whose
image data are stored in a piddle. These include methods for
convolutions (smoothing), polygon fills, scaling, rotation, and warping,
Contains a few functions that are conceptually related to
image processing, but which can be defined for higher-dimensional data.
For examples this module defines high-dimensional convolution and
interpolation, among others.
Defines some useful functions for working with RBG image data.
It's not very feature-full, but it may have something you need, and if
not, you can always add more!
Creates the transform class, which allows you to create
various coordinate transforms. For example, if you data is a collection
of Cartesian coordinates, you could create a transform object to convert
them to Spherical-Polar coordinates (although many such standard
coordinate transformations are predefined for you, in this case it's
This package states that it "implements the commonly used
simplex optimization algorithm." I'm going to assume that if you
need this algorithm then you already know what it is.
A collection of fairly standard math functions, like the
inverse trigonometric functions, hyperbolic functions and their
inverses, and others. This module is included in the standard call to
"use PDL", but not in the Lite
Provides a few functions that use the standard mathematical
Matrix notation of row-column indexing rather than the PDL-standard
column-row. It appears that this module has not been heavily tested with
other modules, so although it should work with other modules, don't be
surprised if something breaks when you use it (and feel free to offer
any fixes that you may develop).
Provides many standard matrix operations for piddles, such as
computing eigenvalues, inverting square matrices, LU-decomposition, and
solving a system of linear equations. Though it is not built on
PDL::Matrix, it should generally work with that module. Also, the
methods provided by this module do not depend on external libraries such
as Slatec or GSL.
Implements an interface to all the functions that return
piddles with one less dimension (for example,
"sumover"), such that they can be
called by suppling their name, as a string.
The sorts of modules and documentation that you'll use if you write modules that
use PDL, or if you work on PDL maintenance. These modules can be difficult to
use, but enable you to tackle some of your harder problems.
Enables Matlab-style autoloading. When you call an unknown
function, instead of complaining and croaking, PDL will go hunt around
in the directories you specify in search of a like-named file.
Particularly useful when used with the Perldl Shell.
Declares the "px" function,
which can be handy for debugging your PDL scripts and/or perldl shell
Suppose you define a powerful, versatile function. Chances are
good that you'll accept the arguments in the form of a hash or hashref.
Now you face the problem of processing that hashref. PDL::Options
assists you in writing code to process those options. (You'd think Perl
would have tons of these sorts of modules lying around, but I couldn't
find any.) Note this module does not depend on PDL for its usage or
Ever fired-up the perldl shell just to look up the help for a
particular function? You can use
"pdldoc" instead. This shell script
extracts information from the help index without needing to start the
- PDL::Lite, PDL::LiteF
Lite-weight replacements for "use
PDL", from the standpoint of namespace pollution and load
This was mentioned earlier. Before you begin reading about
PDL::PP (next), you should remind yourself about how to use this.
Inline::Pdlpp will help you experiment with PDL::PP without having to go
through the trouble of building a module and constructing makefiles (but
see PDL::pptemplate for help on that).
The PDL Pre-Processor, which vastly simplifies making you C or
Fortran code play with Perl and piddles. Most of PDL's basic
functionality is written using PDL::PP, so if you're thinking about how
you might integrate some numerical library written in C, look no
A script that automates the creation of modules that use
PDL::PP, which should make your life as a module author a bit
Allows you to call functions using external shared libraries.
This is an alternative to using PDL::PP. The major difference between
PDL::PP and PDL::CallExt is that the former will handle threading over
implicit thread dimensions for you, whereas PDL::CallExt simply calls an
external function. PDL::PP is generally the recommended way to interface
your code with PDL, but it wouldn't be Perl if there wasn't another way
to do it.
Defines the %PDL::Config hash, which
has lots of useful information pertinent to your PDL build.
Explanation of the PDL documentation conventions, and an
interface to the PDL Documentation parser. Following these guidelines
when writing documentation for PDL functions will ensure that your
wonderful documentation is accessible from the perldl shell and from
calls to "barf". (Did you notice that
"barf" used your documentation? Time
to reread PDL::Core...)
A simple replacement for the standard Exporter module. The
only major difference is that the default imported modules are those
Defines some useful functions for getting a piddle's type, as
well as getting information about that type.
Simply defines the scalar
$PDL::Version::Version with the current version
of PDL, as defined in PDL.pm. This is most useful if you distribute your
own module on CPAN, use PDL::Lite or PDL::LiteF and want to make sure
that your users have a recent-enough version of PDL. Since the variable
is defined in PDL.pm, you don't need this module if you
Copyright 2010 David Mertens (email@example.com). You can distribute
and/or modify this document under the same terms as the current Perl license.
Provides some decently useful functions that are pretty much
only needed by the PDL Porters.
Explains how to make a piddle by hand, from Perl or
your C source code, using the PDL API.
Explains the nitty-gritty of the PDL data structures. After
reading this (a few times :), you should be able to create a piddle
completely from scratch (i.e. without using the PDL API). Put a little
differently, if you want to understand how PDL::PP works, you'll need to
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.