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 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::Ops

  Defines the standard Perl-overloadable operators, like + and .=, for example. Since pretty much all of these operators and functions are discussed elsewhere, there's usually no need to read this documentation or use this module.

• 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 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. But if you don't use mathematical or I/O functions or matrix operations, you might get quicker startup with PDL::LiteF, or that plus no namespace pollution with PDL::Lite.

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::Dataflow

  Covers data flow, which is a somewhat unique feature of PDL.

• 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.

• 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!

Libraries

• 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.

• 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::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 LAPACK 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.

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.