COURSE(1) User Contributed Perl Documentation COURSE(1)NAMEPDL::Course - A journey through PDL's documentation, from beginner to
advanced.
AUTHOR, DATE
This is written by David Mertens with edits by Daniel Carrera.
Preface
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.
Introductory
If you are new to PDL, these documentation modules will get you started
down the right path for using PDL.
Documentation
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 piddle-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 piddle, will create a piddle 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 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 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".
Workflow
· 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!
Libraries
· PDL
The main workhorse module. You'll include this in nearly every PDL
program you write.
Normal Usage
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.
Documentation
· 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 a piddle 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!
Libraries
· PDL::Complex
Complex number support. No, PDL does not have complex number
support built into the core, but this should help you out.
· 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 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 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 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.
· 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 a piddle. 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 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.
· PDL::Reduce
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.
Workflow
· 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.
Advanced Usage
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 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 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 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.
· 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 a piddle's type, as well
as getting information about that type.
· PDL::Version
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 "use PDL".
Expert Usage
· PDL::Core::Dev
Provides some decently useful functions that are pretty much only
needed by the PDL Porters.
· PDL::API
Explains how to make a piddle 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 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 read this.
COPYRIGHT
Copyright 2010 David Mertens (dcmertens.perl@gmail.com). You can
distribute and/or modify this document under the same terms as the
current Perl license.
See: http://dev.perl.org/licenses/
perl v5.18.1 2013-05-12 COURSE(1)
