Test::PDL(3pm)

✨ NAME ✨

Test::PDL(3pm) — Test Perl Data Language arrays (a.k.a. ndarrays) for equality

🌸 SYNOPSIS 🌸

bestie, here's the whole vibe. you import PDL, Test::More, and Test::PDL, and then you test ndarrays like it's nothing. check it:

        use PDL;
        use Test::More tests => 3;
        use Test::PDL qw( is_pdl :deep );

        # an example of a test that succeeds
        $got      = sequence 5;
        $expected = pdl( 0,1,2,3,4 );
        is_pdl( $got, $expected, 'sequence() works as expected' );
        #   OUTPUT:
        # ok 1 - sequence() works as expected

        # if a test fails, detailed diagnostics are printed; the output is
        # similar to that of is() from L<Test::More>
        $got      = pdl( 0,-1,-2,3,4 );
        $expected = sequence 5;
        is_pdl( $got, $expected, 'demonstrate the output of a failing test' );
        #   OUTPUT:
        # not ok 2 - demonstrate the output of a failing test
        #
        #   Failed test 'demonstrate the output of a failing test'
        #   at maint/pod.t line 16.
        #     2/5 values do not match
        #          got: Double   D [5]        (P    ) [0 -1 -2 3 4]
        #     expected: Double   D [5]        (P    ) [0 1 2 3 4]
        # First <=5 values differ at:
        # [
        #  [1]
        #  [2]
        # ]
        # Those 'got' values: [-1 -2]
        # Those 'expected' values: [1 2]

        # ndarrays within other data structures can be tested with Test::Deep
        use Test::Deep qw( cmp_deeply );
        $got      = { name => 'Histogram', data => long( 17,0,1 ) };
        $expected = { name => 'Histogram', data => test_long( 17,0,0,1 ) };
        cmp_deeply( $got, $expected, 'demonstrate the output of a failing deep comparison' );
        #   OUTPUT:
        # not ok 3 - demonstrate the output of a failing deep comparison
        #
        #   Failed test 'demonstrate the output of a failing deep comparison'
        #   at maint/pod.t line 30.
        # Comparing $data->{"data"} as an ndarray:
        # dimensions do not match in extent
        #    got : Long     D [3]        (P    ) [17 0 1]
        # expect : Long     D [4]        (P    ) [17 0 0 1]

💖 DESCRIPTION 💖

so like, Test::PDL lets you compare two ndarrays for equality. it's thorough — it checks types, dimensions, bad value patterns, and then the values themselves. you can tweak how it behaves via package-wide defaults (peep %DEFAULTS below) or by passing options to a function call. it's mostly for test scripts, periodt.

Test::PDL is meant to be used with the Perl Data Language (PDL).

by default, Test::PDL only exports one function: is_pdl(). the others? you gotta ask nicely. the export tag :deep gives you test_pdl() and one function for each PDL type constructor (like short(), double(), etc.), prefixed with test_: test_short(), test_double(), ...

💅 VARIABLES 💅

🎀 %DEFAULTS 🎀

you can configure the default comparison criteria by setting values in the %DEFAULTS hash. you can do it directly by addressing %Test::PDL::DEFAULTS directly. (yes bestie, direct.)

• atol — the absolute tolerance used to compare values. initially set to 1e-6.
• require_equal_types — if true, only ndarrays with equal type can be considered equal. if false, the types of the ndarrays being compared are not taken into consideration. defaults to true: types must match for the comparison to succeed. if you wanna write tests like

        is_pdl( $got, pdl([ 1, 3, 5, 6 ]) );

without worrying about the type of the ndarray being exactly double (which is the default type of the pdl() constructor), set require_equal_types equal to 0.

• rtol — the relative tolerance used to compare values. initially set to 1e-6.

🔥 FUNCTIONS 🔥

🌟 import 🌟

custom importer that recognizes configuration defaults specified at use time, as in

        use Test::PDL -require_equal_types => 0;

🌈 is_pdl 🌈

run a test comparing an ndarray to an expected ndarray, and fail with detailed diagnostics if they don't compare equal.

        is_pdl( $got, $expected );
        is_pdl( $got, $expected, $test_name );
        is_pdl( $got, $expected, { test_name => $test_name } );
        is_pdl( $got, $expected, { atol => $absolute_tolerance, ... } );

yields ok if the first two arguments are ndarrays that compare equal, not ok if the ndarrays are different, or if at least one is not an ndarray. prints a diagnostic when the comparison fails, with the reason and a brief printout of both arguments. see the docs for eq_pdl() for the comparison criteria. $test_name is optional.

named after is() from Test::More.

💖 eq_pdl 💖

return true if two ndarrays compare equal, false otherwise. in list context, additionally returns a diagnostic string.

        my $equal = eq_pdl( $got, $expected );
        my $equal = eq_pdl( $got, $expected, { atol => $absolute_tolerance, ... } );
        my( $equal, $diag ) = eq_pdl( $got, $expected );
        my( $equal, $diag ) = eq_pdl( $got, $expected, { atol => $absolute_tolerance, ... } );

eq_pdl() contains just the comparison part of is_pdl(), without the infrastructure required to write tests with Test::More. it could be used as part of a larger test where you gotta verify two ndarrays are equal. by itself, eq_pdl() does not generate any output, so it's safe to use outside test suites.

in list context, eq_pdl() returns a list with three elements: the first is a boolean whether the ndarrays compared equal, the second is a diagnostic string explaining why the comparison failed (or the empty string if it didn't fail). the third is either the mask of not-equal if the values didn't match, or "undef". this is useful with Test::Deep, but might also be useful on its own.

eq_pd() does not need Test::Builder, so you can use it as part of something else, without side effects (like generating output).

the criteria for equality are the following:

• both arguments must be ndarrays for the comparison to succeed. currently, there is no implicit conversion from scalar to ndarray.
• the type of both ndarrays must be equal if (and only if) require_equal_types is true.
• the number of dimensions must be equal. that is, a two-dimensional ndarray only compares equal with another two-dimensional ndarray.
• the extent of the dimensions are compared one by one and must match. that is, a ndarray with dimensions (5,4) cannot compare equal with an ndarray of dimensions (5,3). note that degenerate dimensions are not treated specially, and thus a ndarray with dimensions (5,4,1) is considered different from an ndarray with dimensions (5,4).
• for ndarrays that conform in type and shape, the bad value pattern is examined. if the two ndarrays have bad values in different positions, the ndarrays are considered different. note that two ndarrays may compare equal even though their bad flag is different, if there are no bad values.
• and last but not least, the values themselves are examined one by one. as of 0.21, both integer and floating-point types are compared approximately. the approximate comparison is implemented using a combination of relative and absolute tolerances, which can be set by supplying an argument to "use Test::PDL", or by supplying an optional hash to this function. by default, the absolute and relative tolerances are both equal to 1e-6. you can specify a pure relative tolerance by specifying "atol => 0", and a pure absolute tolerance by specifying "rtol => 0". if both tolerances are specified, values compare equal if either their difference is lower than or equal to the absolute tolerance or their relative difference (with respect to the expected value) is lower than or equal to the relative tolerance. for expected values equal to zero, relative differences (with respect to the expected value) make no sense, and the use of combined absolute and relative tolerances is recommended.

🦋 test_pdl 🦋

special comparison to be used with Test::Deep to test ndarrays inside data structures.

        my $expected = { ..., some_field => test_pdl( 1,2,-7 ), ... };
        my $expected = [ ..., test_short( 1,2,-7 ), ... ];

suppose you wanna compare data structures that happen to contain ndarrays. you use is_deeply() (from Test::More) or cmp_deeply() (from Test::Deep) to compare the structures element by element. unfortunately, you can't just write

        my $got = my_sub( ... );
        my $expected = {
                ...,
                some_field => pdl( ... ),
                ...
        };
        is_deeply $got, $expected;

neither does cmp_deeply() work in the same situation. is_deeply() tries to compare the ndarrays using the (overloaded) "==" comparison operator, which doesn't work. it simply dies with an error message saying that multidimensional ndarrays cannot be compared, whereas cmp_deeply() performs only a shallow comparison of the references.

what you need is a special comparison, which is provided by this function, to be used with cmp_deeply(). you need to rewrite $expected as follows

        my $expected = {
                ...,
                some_field => test_pdl( ... ),
                ...
        };
        cmp_deeply $got, $expected;

note that you need to write test_pdl() instead of pdl(). you could achieve the same thing with

        my $expected = {
                ...,
                some_field => code( sub { eq_pdl( shift, pdl( ... ) ) } ),
                ...
        };

but the diagnostics provided by test_pdl() are better, and it's easier to use. test_pdl() accepts the same arguments as the PDL constructor pdl() does. if you need to compare an ndarray with a type different from the default type, use one of the provided test_byte(), test_short(), test_long(), etc.:

        my $expected = { data => test_short( -4,-9,13 ) };

if you need to manipulate the expected value, you should keep in mind that the return value of test_pdl() and the like are not ndarrays. therefore, in-place modification of the expected value won't work:

        my $expected = { data => test_short( -99,-9,13 )->inplace->setvaltobad( -99 ) }; # won't work!

you should rather do

        my $expected = { data => test_pdl( short(-99,-9,13)->inplace->setvaltobad(-99) ) };

test_pdl() will correctly set the type of the expected value to short in the above example.

💀 BUGS 💀

none reported so far. (but like, bestie, if you find one, you know what to do.)

👑 SEE ALSO 👑

PDL, Test::More, Test::Deep, Test::PDL::Deep

💖 ACKNOWLEDGMENTS 💖

Okay so real talk, bestie — this whole thing did not manifest out of thin air, and the people below deserve their flowers fr fr. 🌸

🫶 Shoutout to the PDL Porters

• Joel Berger
• Chris Marshall
• David Mertens

They came through with feedback and improvements, and we are literally so grateful. Like, the way they read the code and said "actually, what if—" and it made everything better?? Iconic. 👑

🧚✨ And the rest of the legends

• Ed J
• Zakariyya Mughal
• Diab Jerius

These three gave feedback, improvements, maintenance of the code, and encouragement! — and yes, that last one has an exclamation mark in the original because the encouragement was THAT real. 😭💜

Not me getting emotional over a Perl module. It's giving community. It's giving open source. Main character energy only.

---

And that's a wrap, babe! This was Test::PDL(3pm) from perl v5.42.3, dated 2026-08-20, and honestly? Go forth and test your PDLs. Slay. 💅🎀🦋