- AUTHOR, DATE
- Normal Usage
- Advanced Usage
- Expert Usage
PDLA::Course - A journey through PDLA's documentation, from beginner to advanced.
This is written by David Mertens with edits by Daniel Carrera.
PDLA'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 PDLA 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 PDLA, these documentation modules will get you started down the right path for using PDLA.
Modules that tell you how to start using PDLA. Many of these are library modules technically, but they are included when you
use PDLA, 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 PDLA.
A couple of brief introductions to PDLA. The second one is a bit more hands-on. If you are new to PDLA, you should start with these.
Covers basic piddle-creation routines like
logxvalsto name a random few. Also covers
Explains a large collection of built-in functions which, given an N-dimension piddle, will create a piddle with N-1 dimensions.
PDLA 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.
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 PDLA::Core
Like PDLA::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
The Perldl Shell is a REPL (Read-Evaluate-Print-Loop, in other words, a prompt or shell) that allows you to work with PDLA (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 PDLA Shell, with instant feedback!
The main workhorse module. You'll include this in nearly every PDLA program you write.
The sorts of modules that you'll likely use on a normal basis in scripts or from within the perldla 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.
In addition to explaining the original slicing and dicing functions - for which you can usually use PDLA::NiceSlice - this also covers many dimension-handling functions such as
reorder. This also thoroughly documents the
rangefunction, 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 PDLA 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 PDLA enlightenment.
PDLA 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 PDLA.
Explains what bad values are and how and why they are implemented.
Selections from Inline::Pdlapp
Although writing PDLA::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 PDLA-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 PDLA::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 PDLA 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!
Complex number support. No, PDLA does not have complex number support built into the core, but this should help you out.
PDLA's own Fast Fourier Transform. If you have FFTW, then you should probably make use of it; this is PDLA's internal implementation and should always be available.
PDLA 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 PDLA has the GSL bindings. For a full list of the GSL bindings, check PDLA::Index.
A somewhat uniform interface to the different interpolation modules in PDLA.
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 (
setbadif). Among other places, bad values are used in PDLA::Graphics::PLplot's xyplot to make a gap in a line plot.
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 PDLA::DiskCache.
A PDLA subclass that allows you to store and manipulate collections of fixed-length character strings using PDLA.
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.
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 called
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 PDLA, but not in the Lite versions.
Provides a few functions that use the standard mathematical Matrix notation of row-column indexing rather than the PDLA-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 PDLA::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.
Enables Matlab-style autoloading. When you call an unknown function, instead of complaining and croaking, PDLA will go hunt around in the directories you specify in search of a like-named file. Particularly useful when used with the Perldl Shell.
pxfunction, which can be handy for debugging your PDLA scripts and/or perldla shell commands.
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. PDLA::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 PDLA for its usage or installation.
Ever fired-up the perldla shell just to look up the help for a particular function? You can use
pdladocinstead. This shell script extracts information from the help index without needing to start the perldla shell.
The sorts of modules and documentation that you'll use if you write modules that use PDLA, or if you work on PDLA maintenance. These modules can be difficult to use, but enable you to tackle some of your harder problems.
Lite-weight replacements for
use PDLA, from the standpoint of namespace pollution and load time.
This was mentioned earlier. Before you begin reading about PDLA::PP (next), you should remind yourself about how to use this. Inline::Pdlapp will help you experiment with PDLA::PP without having to go through the trouble of building a module and constructing makefiles (but see PDLA::pptemplate for help on that).
The PDLA Pre-Processor, which vastly simplifies making you C or Fortran code play with Perl and piddles. Most of PDLA's basic functionality is written using PDLA::PP, so if you're thinking about how you might integrate some numerical library written in C, look no further.
A script that automates the creation of modules that use PDLA::PP, which should make your life as a module author a bit simpler.
Allows you to call functions using external shared libraries. This is an alternative to using PDLA::PP. The major difference between PDLA::PP and PDLA::CallExt is that the former will handle threading over implicit thread dimensions for you, whereas PDLA::CallExt simply calls an external function. PDLA::PP is generally the recommended way to interface your code with PDLA, but it wouldn't be Perl if there wasn't another way to do it.
%PDLA::Confighash, which has lots of useful information pertinent to your PDLA build.
Explanation of the PDLA documentation conventions, and an interface to the PDLA Documentation parser. Following these guidelines when writing documentation for PDLA functions will ensure that your wonderful documentation is accessible from the perldla shell and from calls to
barf. (Did you notice that
barfused your documentation? Time to reread PDLA::Core...)
A simple replacement for the standard Exporter module. The only major difference is that the default imported modules are those marked ':Func'.
Defines some useful functions for getting a piddle's type, as well as getting information about that type.
Simply defines the scalar
$PDLA::Version::Versionwith the current version of PDLA, as defined in PDLA.pm. This is most useful if you distribute your own module on CPAN, use PDLA::Lite or PDLA::LiteF and want to make sure that your users have a recent-enough version of PDLA. Since the variable is defined in PDLA.pm, you don't need this module if you
Provides some decently useful functions that are pretty much only needed by the PDLA Porters.
Explains how to make a piddle by hand, from Perl or your C source code, using the PDLA API.
Explains the nitty-gritty of the PDLA data structures. After reading this (a few times :), you should be able to create a piddle completely from scratch (i.e. without using the PDLA API). Put a little differently, if you want to understand how PDLA::PP works, you'll need to read this.
Copyright 2010 David Mertens (firstname.lastname@example.org). You can distribute and/or modify this document under the same terms as the current Perl license.