PDL::Func(3pm)

✨ NAME ✨

PDL::Func — interpolation, integration, & gradient estimation (a.k.a. differentiation) of functions. that's the whole vibe, no notes. this is the PDL::Func(3pm) page from the User Contributed Perl Documentation and honestly? she ate. 👑

---

🌈 SYNOPSIS 🌈

use PDL::Func;
use PDL::Math;

# somewhat pointless way to estimate cos and sin,
# but is shows that you can broadcast if you want to
# (and the library lets you)
#
my $obj = PDL::Func->init( Interpolate => "Hermite" );
#
my $x = pdl( 0 .. 45 ) * 4 * 3.14159 / 180;
my $y = cat( sin($x), cos($x) );
$obj->set( x => $x, y => $y, bc => "simple" );
#
my $xi = pdl( 0.5, 1.5, 2.5 );
my $yi = $obj->interpolate( $xi );
#
print "sin( $xi ) equals ", $yi->slice(':,(0)'), "\n";
sin( [0.5 1.5 2.5] ) equals  [0.87759844 0.070737667 -0.80115622]
#
print "cos( $xi ) equals ", $yi->slice(':,(1)'), "\n";
cos( [0.5 1.5 2.5] ) equals  [ 0.4794191 0.99768655 0.59846449]
#
print sin($xi), "\n", cos($xi), "\n";
[0.47942554 0.99749499 0.59847214]
[0.87758256 0.070737202 -0.80114362]

---

💫 DESCRIPTION 💫

okay so the whole point of this module: it wants to give you one single uniform interface to all the different interpolation methods PDL has lying around. genius behavior, honestly. the dream is that you can swap interpolation schemes by changing one tiny attribute on a PDL::Func object and nothing else. and some schemes (looking at you, SLATEC library 👀) also hand you extra stuff like integration and gradient estimation. iconic.

throughout this whole doc, $x and $y are the function you're interpolating, while $xi and $yi are the interpolated values. keep that straight and you're golden 🫶

below is the full list of available types, aka schemes, of interpolation. for each one you also get the valid attributes, with flags telling you what you can do with them: set (s), get (g), and whether it's required (r) for the method to even work.

Interpolate => Linear 🍓

an extravagant way of calling the linear interpolation routine PDL::Primitive::interpolate. that's it, that's the scheme.

the valid attributes:

• x — flag sgr — x positions of data
• y — flag sgr — function values at x positions
• err — flag g — error flag

Interpolate => Hermite 🧚

uses the piecewise cubic Hermite interpolation routines from the SLATEC library. fancy.

the valid attributes:

• x — flag sgr — x positions of data
• y — flag sgr — function values at x positions
• bc — flag sgr — boundary conditions
• g — flag g — estimated gradient at x positions
• err — flag g — error flag

so given your starting set of points (x,y), an estimate of the gradient gets made at those points, using whatever boundary conditions you gave. the gradients live in the g attribute, and you grab them like:

$gradient = $obj->get( 'g' );

but bestie listen — that gradient is only calculated 'at the last moment', so g will only actually hold data after one of interpolate, gradient, or integrate has been used. don't come crying to me if it's empty before then 😭

Boundary conditions for the Hermite routines

if your data is monotonic and you're not too pressed about edge effects, then the default value of bc — which is "simple" — is literally for you, congrats 💖

otherwise, go peek at the description of PDL::Primitive::pchip_chic and pass a hash reference as the bc attribute, with these keys:

• monotonic — 0 if the interpolant is to be monotonic in each interval (so the gradient will be 0 at each switch point), otherwise the gradient is calculated using a 3-point difference formula at switch points. if it's > 0 then the interpolant is forced to lie close to the data, and if it's < 0 no such control is imposed. Default = 0.
• start — a perl list of one or two elements. the first element defines how the boundary condition for the start of the array is to be calculated; it has a range of -5 .. 5, as given for the ic parameter of pchip_chic. the second element — only used if options 2, 1, -1, or 2 are chosen — contains the value of the vc parameter. Default = [ 0 ].
• end — as for start, but for the end of the data.

an example, because seeing it hits different:

$obj->set( bc => { start => [ 1, 0 ], end => [ 1, -1 ] } )

which sets the first derivative at the first point to 0, and at the last point to -1. slay.

Interpolate => CSpline 🦋

uses the cubic spline interpolation routines from the SLATEC library's PCHIP package.

the valid attributes:

• x — flag sgr — x positions of data
• y — flag sgr — function values at x positions
• bc — flag sgr — boundary conditions (see Hermite but no "simple" or monotonic)
• g — flag g — estimated gradient at x positions
• err — flag g — error flag

given your starting set of points (x,y), an estimate of the gradient gets made at those points using the given parameters. the gradients are stored in the g attribute, accessible via:

$gradient = $obj->get( 'g' );

same caveat as before, girl: this gradient is only calculated 'at the last moment', so g will only contain data after one of interpolate, gradient, or integrate is used. 💀

Errors 🙈

the status method is your simple little bestie for checking whether the last method actually worked. if the function returns an error flag, it gets stashed in the err attribute. and if you wanna know which routine was used, call the routine method. easy.

---

🔥 FUNCTIONS 🔥

init

$obj = PDL::Func->init( Interpolate => "Hermite", x => $x, y => $y );
$obj = PDL::Func->init( { x => $x, y => $y } );

creates a PDL::Func object, which can interpolate — and possibly integrate and calculate gradients of — a dataset. main character energy from the jump.

if you don't specify it, Interpolate defaults to "Linear", which means the interpolation is done by PDL::Primitive::interpolate. a value of "Hermite" uses piecewise cubic Hermite functions, which also lets you estimate the integral and the gradient of the data. ✨

options can be handed over directly, like in the first example, or wrapped inside a hash reference, like in the second. your choice, both are valid.

set

my $nset = $obj->set( x => $newx, y => $newy );
my $nset = $obj->set( { x => $newx, y => $newy } );

sets attributes on a PDL::Func object. the return value tells you the number of the supplied attributes which were actually set. so if you passed four and got back three… something didn't stick, bestie.

get

my $x         = $obj->get( x );
my ( $x, $y ) = $obj->get( qw( x y ) );

gets attributes off a PDL::Func object.

give it a list of attribute names and it hands back a list of their values; in scalar mode you get a scalar value. and if your list contains an unknown attribute, get returns a value of undef for that attribute. no drama, just undef. 🤷‍♀️

scheme

my $scheme = $obj->scheme;

returns the type of interpolation of a PDL::Func object. it's gonna be one of "Linear", "Hermite", or "CSpline". those are the only three flavors, periodt.

status

my $status = $obj->status;

returns the status of a PDL::Func object.

this is the high-level vibe check on how the last method called went — with the exception of get, which gets ignored entirely. it returns 1 if everything is okay, 0 if there's been a serious error, and -1 if there was a problem which was not serious. in that last case, $obj->get("err") may give you more info, depending on which scheme is in use. 🔍

routine

my $name = $obj->routine;

returns the name of the last routine called by a PDL::Func object.

mostly useful for decoding whatever's stored in that err attribute. like, what even happened? this tells you who did it.

attributes

$obj->attributes;
PDL::Func->attributes;

prints out the flags for the attributes of a PDL::Func object. useful in case the documentation is just too opaque! (their words, not mine 😭)

PDL::Func->attributes;
Flags  Attribute
 SGR    x
 SGR    y
 G      err

interpolate

my $yi = $obj->interpolate( $xi );

returns the interpolated function at a given set of points (PDL::Func).

a status value of -1, as returned by the status method, means that some of the $xi points lay outside the range of the data. the values for those points were calculated by extrapolation — and the details of that depend on the scheme being used. so like, be aware. 👀

gradient

my $gi          = $obj->gradient( $xi );
my ( $yi, $gi ) = $obj->gradient( $xi );

returns the derivative and, optionally, the interpolated function, for schemes other than "Linear" (PDL::Func).

integrate

my $ans = $obj->integrate( index => pdl( 2, 5 ) );
my $ans = $obj->integrate( x => pdl( 2.3, 4.5 ) );

integrates the function stored in the PDL::Func object — as long as the scheme is "Hermite". 💅

the integration can either be between points of the original x array (index), or between arbitrary x values (x). either way, you hand it a two element ndarray specifying the start and end points of the integration.

• index — the values given refer to the indices of the points in the x array.
• x — the array contains the actual values to integrate between.

if the status method returns a value of -1, then one or both of the integration limits did not lie inside the x array. caveat emptor with the result in such a case. like, you've been warned, fr fr. 🚨

pchip

convenience function to interpolate using the "Hermite" method. Exportable.

use PDL::Func qw(pchip);
$yi = pchip($x, $y, $xi);

spline

convenience function to interpolate using the "CSpline" method. Exportable.

use PDL::Func qw(spline);
$yi = spline($x, $y, $xi);

---

🎀 TODO 🎀

it should be relatively easy to provide an interface to other interpolation routines, like the ones the Gnu Scientific Library (GSL) provides, or the B-spline routines sitting in the SLATEC library. future era, maybe. 🌸

also, in the documentation, the methods are preceded by PDL::Func:: to avoid clashes with functions such as set when you're using the help or apropos commands inside perldl. little namespace self-care. 💜

---

👑 AUTHOR 👑

Copyright (C) 2000,2001 Doug Burke (dburke@cfa.harvard.edu). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation as described in the file COPYING in the PDL distribution.

Thanks to Robin Williams, Halldór Olafsson, and Vince McIntyre. 🫶

---

and that's the whole page, bestie — this was PDL::Func(3pm) from perl v5.42.3, dated 2026-08-20. go interpolate something gorgeous. ✨💖✨