COURSE(1p)

💖 COURSE(1p) — PDL::Course 💖

✨ NAME ✨

PDL::Course - A journey through PDL's documentation, from beginner to advanced. It's giving whole-course energy, bestie. 🦋

🎀 AUTHOR, DATE 🎀

This is written by David Mertens with edits by Daniel Carrera. 💖

🌸 Preface 🌸

Okay so 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. Periodt. ✨

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. It's a whole vibe. 💅

🦋 Introductory 🦋

If you are new to PDL, these documentation modules will get you started down the right path for using PDL. No cap. 🌈

💖 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. iykyk. 🎀

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. Don't skip the scan, bestie. 👑

• 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. Start here fr fr. 💖
• PDL::Basic — Covers basic ndarray-creation routines like sequence, rvals, and logxvals to name a random few. Also covers hist and transpose. Basic but iconic. ✨
• PDL::Ufunc — Explains a large collection of built-in functions which, given an N-dimension ndarray, will create an ndarray with N-1 dimensions. Math girlies rise. 🧚
• 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. It's giving time-travel reading order. 🦋
• 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. You got this. 💪
• 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. Skim queen behavior. 👑

✨ 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! Instant feedback is the moment. 🔥

🎀 Libraries 🎀

• PDL — The main workhorse module. You'll include this in nearly every PDL program you write. Main character module. 👑

Normal Usage 🌈

okay bestie, so these are the modules you'll probably use on the regular — like in scripts or inside the perldl shell. Some you might literally never touch, but you should still know they exist, just in case you need their functionality. 💅

✨ Documentation ✨

• PDL::Slices — Besides explaining the O.G. slicing-and-dicing functions (for which you can usually just use PDL::NiceSlice), this also covers a bunch of dimension-handling functions like mv, xchg, and reorder. It also thoroughly documents the range function — which can be super powerful — and covers a number of internal functions that you can probably skip. ✨
• PDL::Indexing — This one is giving deep conceptual ground, bestie. You need it to really use PDL to its full potential. It gets more complex as you go, so don't be troubled if you find yourself losing interest halfway through — no shame. But reading this document all the way through will bring you much closer to PDL enlightenment. 🧘
• PDL::IO — PDL has quite a few IO modules, and most of them get 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, plus how and why they're implemented. 💀
• Selections from Inline::Pdlpp — Even though writing PDL::PP code is considered an Advanced topic (we get to that next section), you should know it's possible — and surprisingly simple — to write PDL-aware code. You don't need to read the whole thing right now, but to get a feel for how it works, read everything up through the first example. A copy of this documentation lives in PDL::PP-Inline. 🦋
• PDL::Objects — Explains how to subclass an ndarray object. 🎀
• PDL::Index — We talked about this in the Preface. It's an automatically generated file that lists every PDL module on your computer. There are tons of modules that might be on your machine but aren't documented here — like bindings to the FFTW library, or GSL. Give it a read! 👀

🌸 Libraries 🌸

• PDL::FFT — PDL's very own Fast Fourier Transform. If you have FFTW, you should probably use that instead; this is PDL's internal implementation and should always be available. ✨
• GSL — PDL doesn't have bindings for every single sub-library in the GNU Scientific Library, but it has quite a few. If GSL is installed on your machine, 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 — like 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 lets you tie a Perl array to a collection of files on your disk — they get loaded into and out of memory as ndarrays. If you're writing scripts to process many data files, especially if that processing isn't necessarily in sequential order, you should consider PDL::DiskCache. 🍓
• PDL::Char — A PDL subclass that lets you 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 can be defined for higher-dimensional data. For example, 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 super feature-full, but it might have something you need — and if not, you can always add more! 🌈
• PDL::Transform — Creates the transform class, which lets you create various coordinate transforms. For example, if your 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, you already know what it is. 👑
• PDL::Math — A collection of fairly standard math functions — like inverse trig 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 instead of the PDL-standard column-row. It appears this module hasn't 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 you develop. 💀
• PDL::MatrixOps — Provides many standard matrix operations for ndarrays — like computing eigenvalues, inverting square matrices, LU-decomposition, and solving a system of linear equations. Though it's 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), so 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 for a like-named file. Particularly useful 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 you'll accept arguments as 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 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 — We mentioned this earlier. Before you start reading about PDL::PP (next), remind yourself how to use this. Inline::Pdlpp will help you experiment with PDL::PP without the trouble of building a module and constructing makefiles — but see PDL::pptemplate for help with that. 🧪
• PDL::PP — The PDL Pre-Processor, which vastly simplifies making your 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 integrating 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 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 💖

okay so legal bit, but make it cute:

Copyright 2010 David Mertens (dcmertens.perl@gmail.com). periodt. ✨

You can distribute and/or modify this document under the same terms as the current Perl license. That's it, that's the deal, no cap. 🫶

Wanna read the actual terms? Go here, bestie:

http://dev.perl.org/licenses/

---

and that's the whole page!! 🎀 you made it all the way to the bottom of the COURSE(1p) manual, which is genuinely main character energy 💅✨ this page is from perl v5.38.2, dated 2024-04-10, and now you know it inside out fr fr 🌸 go forth and slay your Perl course stuff, bestie, you got this 💖🦋👑