PDL::Core(3pm)

📦

version 2.106 · 9 versions

💖 PDL::Core — the whole vibe, part 1 💖

okay bestie, welcome to PDL::Core(3pm) — that's the section-3pm manual page from the User Contributed Perl Documentation, and it's the beating heart of PDL. Sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

PDL::Core — the fundamental PDL functionality plus vectorization/broadcasting. that's the whole thing, she's the main character 👑

🌸 DESCRIPTION 🌸

Methods and functions for type conversions, PDL creation, type conversion, broadcasting etc.

(yes, "type conversion" really does show up twice in there. we said what we said. 💅)

🦋 SYNOPSIS 🦋

use PDL::Core;             # Normal routines
use PDL::Core ':Internal'; # Hairy routines

so like, normal girlies do the first one, and the hairy-routine girlies do the second. both are valid.

🌈 VECTORIZATION/BROADCASTING: METHOD AND NOMENCLATURE 🌈

PDL gives you vectorized operations through a built-in engine. the name of the game is "broadcasting" — though fr fr, up until version 2.074 it was called "threading", so if you see old posts calling it that, you're not confused, the lore just changed. the broadcasting engine has simple rules for each operation.

Every PDL object has a "shape" — a generalized N-dimensional rectangle defined by a "dim list" of sizes in an arbitrary set of dimensions. a PDL with shape 2x3 has 6 elements, is two-dimensional, and might get called a "2x3-PDL". dimensions are indexed numerically starting at 0, so a 2x3-PDL has a dimension 0 (or "dim 0") with size 2, and a 1 dimension (or "dim 1") with size 3.

PDL generalizes all mathematical operations with the notion of "active dims": each operator has zero or more active dims that are used in carrying out the operation. simple scalar operations like scalar multiplication ('*') have 0 active dims. more complicated operators can have more active dims. for example, matrix multiplication ('x') has 2 active dims. additional dims are automatically vectorized across — e.g. multiplying a 2x5-PDL with a 2x5-PDL requires 10 simple multiplication operations, and yields a 2x5-PDL result. slay 🫶

✨ Broadcasting rules ✨

In any PDL expression, the active dims appropriate for each operator are used starting at the 0 dim and working forward through the dim list of each object. all additional dims after the active dims are "broadcast dims". broadcast dims do not have to agree exactly — they get coerced to agree according to these simple rules:

Null PDLs match any dim list (see below). 👀
Dims with sizes other than 1 must all agree in size.
Dims of size 1 are silently repeated as necessary — except for "[phys]" PDLs.
Missing dims are expanded appropriately.

A size-1 dim for "[phys]" PDLs causes an exception if the dim is used in another parameter and has a size greater than 1. ⚠️

The "size 1" rule implements "generalized scalar" operation, by analogy to scalar multiplication. the "missing dims" rule acknowledges the ambiguity between a missing dim and a dim of size 1.

🎀 Null PDLs 🎀

PDLs on the left-hand side of assignment can have the special value "Null". a null PDL has no dim list and no set size; its shape is determined by the computed shape of the expression being assigned to it. null PDLs contain no values and can only be assigned to. once you assign to one (e.g. via the .= operator), it stops being a null PDL. glow up moment ✨

To create a null PDL, use "PDL->null()".

💜 Empty PDLs 💜

PDLs can represent the empty set using "structured Empty" variables. and no — an empty PDL is not a null PDL, don't play them like that 🙈

Any dim of a PDL can be set explicitly to size 0. if you do that, the PDL contains zero values — because the total number of values is the product of all the sizes in the PDL's shape or dimlist. math is math.

Scalar PDLs are zero-dimensional and have no entries in the dim list, so they cannot be empty. 1-D and higher PDLs can be empty. empty PDLs are useful for set operations, and are most commonly encountered in the output from selection operators such as which and whichND. not all empty PDLs have the same broadcasting properties — e.g. a 2x0-PDL represents a collection of 2-vectors that happens to contain no elements, while a simple 0-PDL represents a collection of scalar values (that also happens to contain no elements).

Heads up bestie: 0 dims are not adjustable via the broadcasting rules — a dim with size 0 can only match a corresponding dim of size 0 or 1. that's the rule, periodt.

🙈 Broadcast rules and assignments 🙈

Versions of PDL through 2.4.10 have some irregularity with broadcasting and assignments. currently the broadcasting engine performs a full expansion of both sides of the computed assignment operator .= (which assigns values to a pre-existing PDL). this leads to counter-intuitive behavior in some cases:

Empty PDLs and generalized scalars

Generalized scalars (PDLs with a dim of size 1) can match any size in the corresponding dim, including 0. Thus,

$x = ones(2,0);
$y = sequence(2,1);
$c = $x * $y;
print $c;

prints "Empty[2,0]".

This behavior is counterintuitive but desirable, and will be preserved in future versions of PDL.

💅 VARIABLES 💅

these are important variables of global scope, and they live in the PDL namespace.

$PDL::debug — when true, PDL debugging information is printed.
$PDL::verbose — when true, PDL functions provide chatty information.
$PDL::use_commas — whether to insert commas when printing pdls.
$PDL::floatformat, $PDL::doubleformat, $PDL::indxformat — the default print format for floats, doubles, and indx values, respectively. the default default values are:

$PDL::floatformat  = "%7g";
$PDL::doubleformat = "%10.8g";
$PDL::indxformat   = "%12d";

$PDL::infoformat — the default format for "info". the default value is:

$PDL::infoformat = "%C: %T %D";

$PDL::undefval — the value to use instead of "undef" when creating pdls. if it is "undef", 0 will be used.
$PDL::toolongtoprint — the maximal size pdls to print (defaults to 10000 elements).

🔥 FUNCTIONS 🔥

🫶 `barf` 🫶

the standard error reporting routine for PDL.

barf() is the routine PDL modules should call to report errors. this is because barf() will report the error as coming from the correct line in the module user's script rather than in the PDL module. icon behavior honestly.

For now, barf just calls Carp::confess()

Remember barf() is your friend. Use it!

At the perl level:

barf("User has too low an IQ!");

In C or XS code:

barf("You have made %d errors", count);

Note: this is one of the few functions ALWAYS exported by PDL::Core. 💖

🧚 `pdl` 🧚

PDL constructor — creates new ndarray from perl scalars/arrays, ndarrays, and strings.

$double_pdl = pdl(SCALAR|ARRAY REFERENCE|ARRAY|STRING);  # default type
$type_pdl   = pdl(PDL::Type,SCALAR|ARRAY REFERENCE|ARRAY|STRING);

$x = pdl [1..10];                    # 1D array of doubles
$x = pdl ([1..10]);                  # 1D array
$x = pdl (1,2,3,4);                  # Ditto
$y = pdl [[1,2,3],[4,5,6]];          # 2D 3x2 array
$y = pdl "[[1,2,3],[4,5,6]]";        # Ditto (slower)
$y = pdl "[1 2 3; 4 5 6]";           # Ditto
$y = pdl q[1 2 3; 4 5 6];            # Ditto, using the q quote operator
$y = pdl "1 2 3; 4 5 6";             # Ditto, less obvious, but still works
$y = pdl 42                          # 0-dimensional scalar
$c = pdl $x;                         # Make a new copy

$u = pdl ushort(), 42                # 0-dimensional ushort scalar
$y = pdl(byte(),[[1,2,3],[4,5,6]]);  # 2D byte ndarray

$n = pdl indx(), [1..5];             # 1D array of indx values
$n = pdl indx, [1..5];               # ... can leave off parens
$n = indx( [1..5] );                 # ... still the same!

$n = pdl cdouble, 2, 3;              # native complex numbers, zero imaginary
use Math::Complex qw(cplx);
$n = pdl cdouble, 2, cplx(2, 1));    # explicit type
$n = pdl 2, cplx(2, 1);              # default cdouble if Math::Complex obj

$x = pdl([[1,2,3],[4,5,6]]);         # 2D
$x = pdl([1,2,3],[4,5,6]);           # 2D

Note the last two are equivalent — a list is automatically converted to a list reference for syntactic convenience. i.e. you can omit the outer "[]". we love a shortcut 😌

You can mix and match arrays, array refs, and PDLs in your argument list, and "pdl" will sort them out. you get back a PDL whose last (slowest running) dim runs across the top level of the list you hand in, and whose first (fastest running) dim runs across the deepest level that you supply.

At the moment, you cannot mix and match those arguments with string arguments, though we can't imagine a situation in which you would really want to do that. 💀

The string version of pdl also allows you to use the strings "bad", "inf", and "nan", and it will insert the values that you mean (and set the bad flag if you use "bad"). you can mix and match case, though you shouldn't. here are some examples:

$bad = pdl q[1 2 3 bad 5 6];  # Set fourth element to the bad value
$bad = pdl q[1 2 3 BAD 5 6];  # ditto
$bad = pdl q[1 2 inf bad 5];  # now third element is IEEE infinite value
$bad = pdl q[nan 2 inf -inf]; # first value is IEEE nan value

The default constructor uses IEEE double-precision floating point numbers. you can use other types, but you will get a warning if you try to use "nan" with integer types (it will be replaced with the "bad" value) and you will get a fatal error if you try to use "inf". ⚠️ no cap, be careful.

Throwing a PDL into the mix has the same effect as throwing in a list ref:

pdl(pdl(1,2),[3,4])

is the same as

pdl([1,2],[3,4]).

All of the dimensions in the list are "padded-out" with undefval to meet the widest dim in the list, so (e.g.)

$x = pdl([[1,2,3],[2]])

gives you the same answer as

$x = pdl([[1,2,3],[2,undef,undef]]);

If your PDL module has bad values compiled into it (see PDL::Bad), you can pass BAD values into the constructor within pre-existing PDLs. the BAD values are automatically kept BAD and propagated correctly. bestie behavior fr fr.

pdl() is a functional synonym for the 'new' constructor, e.g.:

$x = PDL->new([1..10]);

In order to control how undefs are handled in converting from perl lists to PDLs, one can set the variable $PDL::undefval. for example:

$foo = [[1,2,undef],[undef,3,4]];
$PDL::undefval = -999;
$f = pdl $foo;
print $f
[
 [   1    2 -999]
 [-999    3    4]
]

$PDL::undefval defaults to zero.

As a final note, if you include an Empty PDL in the list of objects to construct into a PDL, it is kept as a placeholder pane — so if you feed in (say) 7 objects, you get a size of 7 in the 0th dim of the output PDL. the placeholder panes are completely padded out. but if you feed in only a single Empty PDL, you get back the Empty PDL (no padding). 🎀

⭐ `empty` ⭐

Returns an empty ndarray, with a single zero-length dimension. only available as a function, not a method — she doesn't do methods.

$x = empty; # defaults to lowest type so it can always be promoted up
$x = empty(float);

🌟 `null` 🌟

Returns a 'null' ndarray. it is an error to pass one of these as an input to a function. 🚨

$x = null;

okay that's part 1 bestie, we are SO back — more parts incoming 💖✨

So null() is not like other empties — PDL::PP gives it a whole special meaning 💅 It flags a super specific kind of empty ndarray that's allowed to grow to whatever dimensions it needs to hold a result (which is a totally different vibe from shoving a result into an ndarray that already exists).

pdl> sumover sequence(10,10), $ans=null;p $ans
[45 145 245 345 445 545 645 745 845 945]

🌱 nullcreate

Hands you back a 'null' ndarray. That's it, that's the job 🫶

$x = PDL->nullcreate($arg)

It's the routine a whole bunch of the broadcasting primitives (think sumover, minimum, etc.) call to spin up a null ndarray for the function's output — one that'll actually behave right for derived (or subclassed) PDL objects. classy

For the usage up there: if $arg is a PDL, or a derived PDL, then $arg->null comes back at you. If $arg is a scalar (i.e. a zero-dimensional PDL) then you get PDL->null.

PDL::Derived->nullcreate(10)
  returns PDL::Derived->null.
PDL->nullcreate($pdlderived)
  returns $pdlderived->null.

🔢 nelem

Returns how many elements are hanging out in an ndarray.

$n = nelem($ndarray); $n = $ndarray->nelem;

$mean = sum($data)/nelem($data);

📐 dims

Gives you the ndarray's dimensions as a perl list.

@dims = $ndarray->dims;  @dims = dims($ndarray);

pdl> p @tmp = dims zeroes 10,3,22
10 3 22

Also peep "shape", which hands you back an ndarray instead. 👀

🧭 dimincs

Returns the ndarray's "dimincs" as a perl list, and it reflects any vaffine transformations it happens to be a child of.

@dimincs = $ndarray->dimincs

pdl> p zeroes(10,3,22)->dimincs
1 10 30
pdl> p zeroes(10,3,22)->t->dimincs
10 1 30

🦋 shape

Returns the ndarray dimensions, but as an ndarray this time.

$shape = $ndarray->shape;  $shape = shape($ndarray);

pdl> p $shape = shape zeroes 10,3,22
[10 3 22]

Also check "dims", which returns a perl list. two besties, two formats 💖

🌈 ndims

Returns the number of dimensions in an ndarray. It's literally just an alias for getndims. same energy, different name.

🌈 getndims

Returns the number of dimensions in an ndarray.

$ndims = $ndarray->getndims;

pdl> p zeroes(10,3,22)->getndims
3

📏 dim

Returns the size of the given dimension of an ndarray. Alias for getdim. (yes it's giving twin flames)

📏 getdim

Returns the size of the given dimension.

$dim0 = $ndarray->getdim(0);

pdl> p zeroes(10,3,22)->getdim(1)
3

Heads up bestie — negative indices count from the end of the dims array. And indices beyond the end just return a size of 1. Which makes total sense honestly, because it reflects the idea that any pdl is equivalent to an infinitely dimensional array where only a finite number of dimensions have a size that isn't one. So in that ✨sense✨, a 3D ndarray of shape [3,5,2] is equivalent to a [3,5,2,1,1,1,1,1,....] ndarray. So accordingly,

print $x->getdim(10000);

will print 1 for basically every ndarray you'll ever meet in practice. no cap 🫠

🏗️ topdl

The alternate ndarray constructor — it makes absolutely sure the arg is an ndarray.

$x = topdl(SCALAR|ARRAY REFERENCE|ARRAY);

The difference between pdl() and topdl() is that the latter will just fall through if the argument is already an ndarray. And it returns a reference, NOT a new copy. periodt.

This is lowkey extremely useful when you're writing a function that's fiddling with internals and just assumes it's got an ndarray argument (like for method calls, yk). Using topdl() means nothing breaks if somebody passes you a '2'. 🙈

Btw topdl() is not exported by default — check the example below for how to actually use it.

use PDL::Core ':Internal'; # use the internal routines of
                           # the Core module

$x = topdl 43;             # $x is ndarray with value '43'
$y = topdl $ndarray;       # fall through
$x = topdl (1,2,3,4);      # Convert 1D array

💫 tocomplex

Returns a complex-typed ndarray — either as a total no-op or as a conversion, depends.

$cplx = $pdl->tocomplex;

Not exported. Added in 2.099. 🌸

⚙️ setdims

Sets the ndarray's dimension list. This is a very low-level routine that does not do any checks, so pls use with caution bestie 😭

$ndarray->setdims(\@dimlist);

🔧 set_datatype

Sets the ndarray's data type to the given value (that's the integer identifier for the type, peep "enum" in PDL::Types). Also see "get_datatype". This is an internal function. It errors if the ndarray has child transforms, and it severs if it has a parent. messy but that's the deal 💀

🔍 get_datatype

Internal: returns the numeric value that identifies the ndarray datatype.

$x = $ndarray->get_datatype;

Mainly used for internal routines.

NOTE: get_datatype returns 'just a number' — not any special type object, unlike "type". don't get it twisted.

📦 howbig

Returns the sizeof an ndarray datatype in bytes.

Note that howbig() is not exported by default — example below, as always 🫶

use PDL::Core ':Internal'; # use the internal routines of
                           # the Core module

$size = howbig($ndarray->get_datatype);

Mainly used for internal routines.

NOTE: this is NOT a method! And the reason is literally because get_datatype returns 'just a number', not any special object. mid but consistent.

pdl> p howbig(ushort([1..10])->get_datatype)
2

🔄 update_data_from

Updates an ndarray's internal data from packed data.

$data = read_from_datasource();
$pdl->update_data_from($data);

Throws an exception if the argument is the wrong size for that ndarray. so like, don't test it 🫠

📥 get_dataref

Returns the internal data for an ndarray, as a perl SCALAR ref.

If you're using this to manipulate the SV, then call "upd_data" — but as of 2.099 you're recommended to just use "update_data_from" instead to streamline the whole process. glow-up moment ✨

Most ndarrays keep their internal data in a packed perl string, all to take advantage of perl's memory management. This gives you direct access to that string, which is super handy when you need to manipulate the binary data directly (e.g. for file I/O). If you modify that string, you'll need to call "upd_data" afterward, so the ndarray properly points to the new location of the underlying perl variable.

Calling "get_dataref" automatically physicalizes your ndarray (see "make_physical"). You definitely don't want to do anything to the SV that truncates or deallocates the string, unless you correspondingly call "reshape" to make the PDL match its new data dimension.

You definitely don't want to use get_dataref unless you know what you're doing (or you're actively trying to find out): you can end up scrozzling memory if you shrink or eliminate the string representation of the variable.

Here be dragons. 🐉😭 genuinely, dragons.

🔁 upd_data

Updates the data pointer in an ndarray to match its perl SV.

This is useful if you've been monkeying with the packed string representation of the PDL — which you probably shouldn't be doing anyway. (see "get_dataref".) no notes, just don't 🫶

As of 2.099 you're recommended to just use "update_data_from" instead, to streamline the process.

🆔 broadcastids

Returns the ndarray broadcast IDs as a perl list.

Note that broadcastids() is not exported by default — example time 💅

use PDL::Core ':Internal'; # use the internal routines of
                           # the Core module

@ids = broadcastids $ndarray;

🔒 readonly

Makes an ndarray read-only, and returns the ndarray argument. Which means any future transformation (a.k.a. PDL operation) applied to this ndarray as an output will cause an exception:

$x = sequence(3)->readonly; # also works: $x = sequence(3); $x->readonly;
$y = $x + 1; # fine
$x .= 5; # error
$x += 5; # also error

Not exported.

$x->readonly;

🕵️ is_readonly

Tests whether an ndarray is read-only.

$bool = $x->is_readonly;

Not exported.

$x->is_readonly;

🌊 flowing

Turns on dataflow — forward only, and only for the next operation (cf "inplace") — and returns the ndarray argument. Which means the next transformation (a.k.a. PDL operation) applied to this ndarray will have forward dataflow:

$x = sequence 3;
$y = $x->flowing + 1; # could instead do $x->flowing; $y = $x + 1
$x += 3; # this does not flow, but that would be an infinite loop anyway
print "$y\n"; # [4 5 6]

This replaced "doflow" as of 2.090. See PDL::Dataflow for more. ✨

$x->flowing; flowing($x);

🚩 fflows

Returns whether the ndarray's PDL_DATAFLOW_F flag is set.

🆕 new

The new ndarray constructor method.

$x = PDL->new(SCALAR|ARRAY|ARRAY REF|STRING);

$x = PDL->new(42);             # new from a Perl scalar
$y = PDL->new(@list_of_vals);  # new from Perl list
$z = PDL->new(\@list_of_vals); # new from Perl list reference
$w = PDL->new("[1 2 3]");      # new from Perl string, using
                               # Matlab constructor syntax

Constructs an ndarray from perl numbers and lists and strings, using Matlab/Octave style constructor syntax. iconique 🎀

The string input is pretty versatile, though it's not performance optimized. The whole goal is to make it easy to copy and paste code straight from PDL output, and to offer a familiar Matlab syntax for ndarray construction. As of May, 2010, it was a new feature, so feel free to report bugs or suggest new features. See the documentation for pdl for more examples of usage.

📄 copy

Makes a physical copy of an ndarray.

$new = $old->copy;

Since $new = $old just makes a new reference, the "copy" method exists to let you make real, independent copies. no shared custody here 💅

📋 hdr_copy

Returns an explicit copy of the header of a PDL.

hdr_copy is just a wrapper for the internal routine _hdr_copy, which takes the hash ref itself. That's the routine used to make copies of the header during normal operations whenever the hdrcpy() flag of a PDL is set.

General-purpose deep copies are expensive in perl, so some simple optimization happens:

If the header is a tied array, or a blessed hash ref with an associated method called "copy", then that ->copy method gets called. Otherwise, all elements of the hash are explicitly copied. References are recursively deep copied.

This routine seems to leak memory. 😭 yeah. that's the note. sorry bestie.

🌀 unwind

Returns an ndarray that's the same as the argument, except that all broadcastids have been removed.

$y = $x->unwind;

🧱 make_physical

Makes sure the data portion of an ndarray can be accessed from XS code.

$x->make_physical;
$x->call_my_xs_method;

Ensures that an ndarray gets its own allocated copy of data. Which obviously implies that there are certain ndarrays out there that don't have their own data. These are the so-called virtual ndarrays that make use of the vaffine optimisation (see PDL::Indexing). They don't have their own copy of data at all — instead they just store access information to some (or all) of another ndarray's data. sneaky but legal 😌

Note: this function should not be used unless absolutely necessary, since otherwise memory requirements might be severely increased. Instead of writing your own XS code and needing to call "make_physical", you might want to consider using the PDL preprocessor (see PDL::PP) — which can transparently access virtual ndarrays without needing to physicalise them (though there are exceptions). iykyk 🫶

`make_physvaffine`

The careful cousin of make_physical 💅 If an ndarray's parent isn't a vaffine transformation, it just quietly calls make_physical like nothing happened. But if it is a vaffine transformation, it goes and updates the vaffine transformation bookkeeping. Diligent. Organized. A whole accountant. 🧾✨

`make_physdims`

Makes sure the ndarray's dims are up to date, parent's dimension changes included, and it calls redodims while it's at it. Basically the "did you check the group chat" of dimension maintenance. 🫶

`trans_parent`

Returns a PDL::Trans object — that's the transformation (the PDL operation) that is the parent of this ndarray — or undef if there's no parent at all. Orphan arc. 😭

And bestie, these objects come with their own little methods, so let's go:

parents — Returns a list of ndarrays that are inputs to this trans.
children — Returns a list of ndarrays that are outputs to this trans (specified as [o], [oca], [io], or [t] in Pars).
address — The memory address of the struct.
flags — List of strings of flags set for this trans.
affine — Whether the trans is affine.
offs — Affine-only: the offset into the parent's data.
incs — Affine-only: the dimincs for each of the child's dims.
ind_sizes — The size of each named dim.
inc_sizes — The size of the inc for each use of a named dim.
vtable — This trans's vtable.
$vtable->name — The function name from this vtable.
$vtable->flags — List of strings of flags set for this vtable.
$vtable->par_names — List of 2 array-refs of strings of names of input pars, then output pars, for this vtable.

`trans_children`

Returns a list of PDL::Trans objects (peep trans_parent above 👆) representing each transformation that has this ndarray as an input. It has lore. It has fans. 🌸

`address`

Returns the memory address of the ndarray's struct. ✨

`address_data`

Returns the value of the ndarray struct's data member. 👑

`set_donttouchdata`

Sets the PDL_DONTTOUCHDATA flag and the nbytes to the given value. Super handy for memory-mapping functionality. The nbytes can be left out, and then only the flag gets set — minimal effort, still valid. 💅

`nbytes`

Returns the ndarray's nbytes.

`seed`

Returns the random seed being used by PDL's RNG. 🎲 Not me checking the RNG's birth chart.

`set_debugging`

Sets whether PDL operations print lots of debugging info to standard output. Returns the old value, so you can put it back like the respectful little gremlin you are.

PDL::Core::set_debugging(1);
# ... these operations will have debugging info printed to stdout
PDL::Core::set_debugging(0); # turn it off again

`dummy`

Insert a 'dummy dimension' of given length (defaults to 1). 🎀

No relation to the 'Dungeon Dimensions' in Discworld! (Sir Terry did not consult on this function. Probably.)

Negative positions specify relative to the last dimension, i.e. dummy(-1) appends one dimension at the end, dummy(-2) inserts a dummy dimension in front of the last dim, etc.

If you specify a dimension position larger than the existing dimension list of your PDL, the PDL gets automagically padded with extra dummy dimensions so you get the dim you asked for, in the slot you asked for. But like — this could cause you trouble. Specifically, if you ask for $x->dummy(5000,1), then $x will get 5,000 dimensions, each of rank 1. Five thousand. Not a typo. Bestie. 💀

Because padding at the beginning of the dimension list moves existing dimensions from slot to slot, it's considered unsafe, so automagic padding doesn't work for large negative indices — only for large positive indices.

$y = $x->dummy($position[,$dimsize]);

pdl> p sequence(3)->dummy(0,3)
[
 [0 0 0]
 [1 1 1]
 [2 2 2]
]

pdl> p sequence(3)->dummy(3,2)
[
 [
  [0 1 2]
 ]
 [
  [0 1 2]
 ]
]

pdl> p sequence(3)->dummy(-3,2)
Runtime error: PDL: For safety, <pos> < -(dims+1) forbidden in dummy.  min=-2, pos=-3

`dup`

Duplicates an ndarray along a dimension. Same energy, doubled. 🦋

$x = sequence(3);
$y = $x->dup(0, 2); # doubles along first dimension
# $y now [0 1 2 0 1 2]

`dupN`

Duplicates an ndarray along several dimensions. Ambitious. Multi-hyphenate. ✨

$x = sequence(3,2);
$y = $x->dupN(2, 3); # doubles along first dimension, triples along second
# [
#  [0 1 2 0 1 2]
#  [3 4 5 3 4 5]
#  [0 1 2 0 1 2]
#  [3 4 5 3 4 5]
#  [0 1 2 0 1 2]
#  [3 4 5 3 4 5]
# ]

`inflateN`

Inflates an ndarray along several dimensions — super useful for e.g. Kronecker products. 🎈

cf dupN (yes, they're siblings, and yes, the family resemblance is strong).

$x = sequence(3,2);
$y = $x->inflateN(2, 2); # doubles along first two dimensions
# [
#  [0 0 1 1 2 2]
#  [0 0 1 1 2 2]
#  [3 3 4 4 5 5]
#  [3 3 4 4 5 5]
# ]

`clump`

"Clumps" several dimensions into one large dimension. The vibes are: shove it all in one bag and shake. 🎒

If called with one argument $n, it clumps the first $n dimensions into one. For example, if $x has dimensions (5,3,4) then after

$y = $x->clump(2);   # Clump 2 first dimensions

the variable $y will have dimensions (15,4) and the element $y->at(7,3) refers to the element $x->at(1,2,3). Math checks out, it's giving efficient. 🔥

Use clump(-1) to flatten an ndarray. The method flat is provided as a convenient alias.

Clumping with a negative dimension in general leaves that many dimensions behind — e.g. clump(-2) clumps all of the first few dimensions into a single one, leaving a 2-D ndarray.

If clump is called with an index list with more than one element, it's treated as a list of dimensions that should be clumped together into one. The resulting clumped dim is placed at the position of the lowest index in the list. This convention ensures clump does the expected thing in the usual cases. The following examples demonstrate usage:

zeroes(2,3,5,7)->clump(-1)->info  # PDL: Double D [210]
zeroes(2,3,5,7)->clump(-2)->info  # PDL: Double D [30,7]
zeroes(2,3,5,7)->clump(2)->info   # PDL: Double D [6,5,7]
zeroes(2,3,5,7)->clump(3)->info   # PDL: Double D [30,7]
zeroes(2,3,5,7)->clump(1,2)->info # PDL: Double D [2,15,7]
zeroes(2,3,5,7)->clump(1,3)->info # PDL: Double D [2,21,5]

Data flows back and forth as usual with slicing routines. 🌊

`broadcast_define`

Define functions that support broadcasting at the perl level. ✨

broadcast_define 'tline(a(n);b(n))', over {
 line $_[0], $_[1]; # make line compliant with broadcasting
};

broadcast_define provides some support for broadcasting (see PDL::Indexing) at the perl level. It lets you do things for which you normally would have resorted to PDL::PP (see PDL::PP); however, it's most useful to wrap existing perl functions so the new routine supports PDL broadcasting. 😌

broadcast_define is used to define new broadcasting aware functions. Its first argument is a symbolic representation of the new function to be defined. The string is composed of the name of the new function followed by its signature (see PDL::Indexing and PDL::PP) in parentheses. The second argument is a subroutine that will be called with the slices of the actual runtime arguments as specified by its signature. Correct dimension sizes and minimal number of dimensions for all arguments will be checked (assuming the rules of PDL broadcasting, see PDL::Indexing). No sneaky dimension crimes allowed. 🚨

The actual work is done by the signature class, which parses the signature string, does runtime dimension checks, and the routine broadcastover, which generates the loop over all appropriate slices of pdl arguments and creates pdls as needed.

Similar to pp_def and its OtherPars option, it's possible to define the new function so that it accepts normal perl args as well as ndarrays. You do this by using the NOtherPars parameter in the signature. The number of NOtherPars specified will be passed unaltered into the subroutine given as the second argument of broadcast_define. Let's illustrate this with an example:

PDL::broadcast_define 'triangles(inda();indb();indc()), NOtherPars => 2',
 PDL::over {
   ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
 };

This defines a function triangles that takes 3 ndarrays as input plus 2 arguments which are passed into the routine unaltered. This routine is used to collect lists of indices into a perl scalar that is passed by reference. Each line is preceded by a prefix passed as $_[4]. Here is typical usage:

$txt = '';
triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
print $txt;

resulting in the following output

1,1,0,-1,
2,1,0,-1,
3,1,0,-1,

which is used in PDL::Graphics::TriD::VRML to generate VRML output. Slay, honestly. 🏆

Currently, this is probably not much more than a POP (proof of principle) but is hoped to be useful enough for some real life work.

Check PDL::PP for the format of the signature. Currently, the [t] qualifier and all type qualifiers are ignored. 🙈

`broadcast`

Use explicit broadcasting over specified dimensions (see also PDL::Indexing). 💫

$y = $x->broadcast($dim,[$dim1,...])

$x = zeroes 3,4,5;
$y = $x->broadcast(2,0);
print $y->info; # PDL: Double D [4] T1 [5,3]
$pb = zeroes(3,3);
print $pb->broadcast(0,1)->info; # PDL: Double D [] T1 [3,3]
print $pb->broadcast(0)->info; #  'PDL: Double D [3] T1 [3]
print zeroes(4,7,2,8)->broadcast(2)->info; # PDL: Double D [4,7,8] T1 [2]
print zeroes(4,7,2,8)->broadcast(2,1)->info; # PDL: Double D [4,8] T1 [2,7]
print zeroes(4,7,2,8,5,6)->broadcast(2,4)->info; # PDL: Double D [4,7,8,6] T1 [2,5]
print zeroes(4,7,2,8,5,6)->broadcast1(2)->broadcast2(3)->info; # PDL: Double D [4,7,8,6] T1 [2] T2 [5]

Same as broadcast1, i.e. it uses broadcast id 1. To use broadcast id 2, use broadcast2, or broadcastI in PDL::Slices directly. 🦋

`broadcast1`

Explicit broadcasting over specified dims using broadcast id 1.

$xx = $x->broadcast1(3,1)

Convenience function interfacing to PDL::Slices::broadcastI. 🎀

`broadcast2`

Explicit broadcasting over specified dims using broadcast id 2.

$xx = $x->broadcast2(3,1)

Convenience function interfacing to PDL::Slices::broadcastI.

`broadcast3`

Explicit broadcasting over specified dims using broadcast id 3.

$xx = $x->broadcast3(3,1)

Convenience function interfacing to PDL::Slices::broadcastI.

`sever`

Sever any links of this ndarray to parent ndarrays. Cutting the cord. Setting boundaries. Therapy, but for memory. 💅

In PDL it's possible for an ndarray to be just another view into another ndarray's data. In that case we call this ndarray a virtual ndarray and the original ndarray owning the data its parent. In other languages these alternate views sometimes run by names such as alias or smart reference.

Typical functions that return such ndarrays are slice, xchg, index, etc. Sometimes, however, you'd like to separate the virtual ndarray from its parent's data and just give it a life of its own (so that manipulation of its data doesn't change the parent). This is simply achieved by using sever. For example,

$x = $pdl->index(pdl(0,3,7))->sever;
$x++;       # important: $pdl is not modified!

⚠️ Note that # important: comment — genuinely important. If you skip the sever, $pdl does get modified. Your parent's data is not your data, bestie. 🚨🫶

In many (but not all) circumstances it acts therefore similar to copy. However, bestie, performance is generally better with sever, and also sever doesn't do that whole futile copying thing when it's used on ndarrays that already have their own data. On the other hand, if you really want to make sure you're working on a copy of an ndarray, use copy.

$x = zeroes(20);
$x->sever;   # NOOP since $x is already its own boss!

Again note: sever is not the same as copy! For example,

$x = zeroes(1); # $x does not have a parent, i.e. it is not a slice etc
$y = $x->sever; # $y is now pointing to the same ndarray as $x
$y++;
print $x;
[1]

but

$x = zeroes(1);
$y = $x->copy; # $y is now pointing to a new ndarray
$y++;
print $x;
[0]

✨ info ✨

Return formatted information about an ndarray. Like, a little report card for your ndarray, slay. 💅

$x->info($format_string);

print $x->info("Type: %T Dim: %-15D State: %S");

Returns a string with info about an ndarray. Takes an optional argument to specify the format of information a la sprintf. Format specifiers are in the form "%<width><letter>" where the width is optional and the letter is one of:

T — Type
D — Formatted Dimensions
F — Dataflow status
S — Some internal flags (P=physical, V=Vaffine, C=changed, B=may contain bad data)
C — Class of this ndarray, i.e. "ref $pdl"
A — Address of the ndarray struct as a unique identifier
M — Calculated memory consumption of this ndarray's data area

The default format is "%C: %T %D". This can be modified by assigning to $PDL::infoformat.

🫶 pdump 🫶

Returns a close analogue of the output of "$pdl->dump" as a string. Like that C function, it will not cause any physicalisation of the ndarray. No cap, it just peeks without touching.