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 the expert.
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 different ways.
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 these.
- •
- PDL::Basic
Covers basic ndarray-creation routines like "sequence",
"rvals", and "logxvals" to name a random few. Also
covers "hist" and "transpose".
- •
- PDL::Ufunc
Explains a large collection of built-in functions which, given an
N-dimension ndarray, will create an ndarray with N-1 dimensions.
- •
- PDL::NiceSlice
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 ndarrays. 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 top.
- •
- PDL::Primitive
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!
- •
- PDL
The main workhorse module. You'll include this in nearly every PDL program
you write.
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
functionality.
- •
- PDL::Slices
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 "mv", "xchg", and
"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.
- •
- PDL::Indexing
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::IO
PDL has quite a few IO modules, most of which are discussed in this summary
module.
- •
- PDL::Tips
A collection of some of Tuomas's ideas for making good use of PDL.
- •
- PDL::BadValues
Explains what bad values are and how and why they are implemented.
- •
- 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.
- •
- PDL::Objects
Explains how to subclass an ndarray object.
- •
- PDL::Index
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 read!
- •
- PDL::FFT
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.
- •
- GSL
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.
- •
- PDL::Func
A somewhat uniform interface to the different interpolation modules in
PDL.
- •
- PDL::Bad
Includes some basic bad-value functionality, including functions to query if
an ndarray 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 line plot.
- •
- PDL::DiskCache
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 ndarrays. 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.
- •
- PDL::Char
A PDL subclass that allows you to store and manipulate collections of
fixed-length character strings using PDL.
- •
- PDL::Image2D
A whole collection of methods for manipulating images whose image data are
stored in an ndarray. These include methods for convolutions (smoothing),
polygon fills, scaling, rotation, and warping, among others.
- •
- PDL::ImageND
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.
- •
- PDL::ImageRGB
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!
- •
- PDL::Transform
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 called
"t_spherical").
- •
- PDL::Opt::Simplex
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.
- •
- PDL::Math
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 versions.
- •
- PDL::Matrix
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).
- •
- PDL::MatrixOps
Provides many standard matrix operations for ndarrays, 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.
- •
- PDL::Reduce
Implements an interface to all the functions that return ndarrays with one
less dimension (for example, "sumover"), such that they can be
called by supplying their name, as a string.
- •
- PDL::AutoLoader
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.
- •
- PDL::Dbg
Declares the "px" function, which can be handy for debugging your
PDL scripts and/or perldl shell commands.
- •
- PDL::Options
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 installation.
- •
- PDL::pdldoc
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
perldl shell.
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.
- •
- PDL::Lite, PDL::LiteF
Lite-weight replacements for "use PDL", from the standpoint of
namespace pollution and load time.
- •
- Inline::Pdlpp
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).
- •
- PDL::PP
The PDL Pre-Processor, which vastly simplifies making you C or Fortran code
play with Perl and ndarrays. 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 further.
- •
- PDL::pptemplate
A script that automates the creation of modules that use PDL::PP, which
should make your life as a module author a bit simpler.
- •
- PDL::CallExt
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 broadcasting over implicit
broadcast 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.
- •
- PDL::Config
Defines the %PDL::Config hash, which has lots of useful information
pertinent to your PDL build.
- •
- PDL::Doc
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...)
- •
- PDL::Exporter
A simple replacement for the standard Exporter module. The only major
difference is that the default imported modules are those marked
':Func'.
- •
- PDL::Types
Defines some useful functions for getting an ndarray's type, as well as
getting information about that type.
- •
- PDL::Core::Dev
Provides some decently useful functions that are pretty much only needed by
the PDL Porters.
- •
- PDL::API
Explains how to make an ndarray by hand, from Perl or your C source
code, using the PDL API.
- •
- PDL::Internals
Explains the nitty-gritty of the PDL data structures. After reading this (a
few times :), you should be able to create an ndarray 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 read this.
Copyright 2010 David Mertens (
[email protected]). You can distribute
and/or modify this document under the same terms as the current Perl license.
See:
http://dev.perl.org/licenses/