Ubuntu Manpage: PDL::Course - A journey through PDL's documentation, from beginner to advanced.

NAME

       PDL::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 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".

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

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

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

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

       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.38.2                                       2024-04-10                                         COURSE(1p)