Utils(3pm)

💖 Utils(3pm) — PDL::CCS::Utils 💖

okay bestie, so this is PDL::CCS::Utils, the low-level utilities page for compressed storage sparse PDLs. it's from the User Contributed Perl Documentation corner of the perl world, and honestly? it's giving "tiny toolbox, big brain energy". let's get into it 🎀

---

✨ SYNOPSIS ✨

use PDL;
use PDL::CCS::Utils;

##---------------------------------------------------------------------
## ... stuff happens

yeah that's it. that's the whole vibe. ... stuff happens is doing a LOT of heavy lifting here and we respect it 🙈

---

🌸 FUNCTIONS 🌸

🔥 Non-missing Value Counts 🔥

nnz

Signature: (a(N); indx [o]nnz())

so this one counts the non-zero values in a PDL $a(). for 1d PDLs, it should be equivalent to:

$nnz = nelem(which($a!=0));

for k>1 dimensional PDLs, it projects via number of nonzero elements to N-1 dimensions — meaning it computes the number of nonzero elements along the 1st dimension. it's giving "collapse but make it count" 💅

and the important bit, no cap: the output PDL $nnz() never contains BAD values. periodt.

nnza

Signature: (a(N); eps(); indx [o]nnz())

like nnz() but with a tolerance constant $eps(). for 1d PDLs, it should be equivalent to:

$nnz = nelem(which(!$a->approx(0,$eps)));

and again, bestie, the output PDL $nnz() never contains BAD values. iconic.

---

🦋 Encoding Utilities 🦋

ccs_encode_pointers

Signature: (indx ix(Nnz); indx N(); indx [o]ptr(Nplus1); indx [o]ixix(Nnz))

the general CCS encoding utility, main character energy ✨

so you hand it a dimension of size $N with non-missing values at indices $ix, and it gets you a compressed storage "pointer" vector $ptr. it also returns a vector $ixix() which you can use as an index for $ix() to align its elements with $ptr() along the compressed dimension. cute, right?

and the induced vector $ix->index($ixix) is guaranteed to be stably sorted along dimension $N():

\forall $i,$j with 1 <= $i < $j <= $Nnz :

 $ix->index($ixix)->at($i) < $ix->index($ixix)->at($j)   ##-- primary sort on $ix()
or
 $ixix->at($i)             < $ixix->at($j)               ##-- ... stable

ccs_encode_pointers does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays. so like, heads up on that 🫶

---

🧚 Decoding Utilities 🧚

ccs_decode_pointer

Signature: (indx ptr(Nplus1); indx proj(Nproj); indx [o]projix(NnzProj); indx [o]nzix(NnzProj); PDL_Indx nnzProj)

the general CCS decoding utility — the un-encoding bestie to the encoding one above 💜

it projects indices $proj() from a compressed storage "pointer" vector $ptr(). and if you don't specify $proj(), it just defaults to:

sequence($ptr->dim(0) - 1)

ccs_decode_pointer does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays. noted. 💀

---

🌈 Indexing Utilities 🌈

ccs_xindex1d

Signature: (indx which(Ndims,Nnz); indx a(Na); indx [o]nzia(NnzA); indx [o]nnza(); PDL_Indx sizeNnzA)

this computes indices $nzai() along dimension "Nnz" of $which() whose initial values $which(0,$nzai) match some element of $a(). appropriate for indexing a sparse encoded PDL with non-missing entries at $which() along the 0th dimension, a la dice_axis(0,$a). and important: $which((0),) and $a() must be both sorted in ascending order. don't come in here unsorted, i'm begging 😭

in list context, it returns a list ($nzai,$nnza), where $nnza() is the number of indices found, and $nzai are those "Nnz" indices. in scalar context, it trims the output vector $nzai() to $nnza() elements. context-sensitive, love that for us ✨

ccs_xindex1d does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

ccs_xindex2d

Signature: (indx which(Ndims,Nnz); indx a(Na); indx b(Nb); indx [o]ab(Nab); indx [o]nab())

okay this one is the 2d bestie. it computes indices along dimension "NNz" of $which() corresponding to any combination of values in the Cartesian product of $a() and $b(). appropriate for indexing a 2d sparse encoded PDL with non-missing entries at $which() via the ND-index piddle

$a->slice("*1,")->cat($b)->clump(2)->xchg(0,1)

i.e. all pairs $ai,$bi with $ai in $a() and $bi in $b(). and same warning as its 1d sister: $a() and $b() values must be be sorted in ascending order. (yes, the original says "must be be sorted" — we're preserving that typo fr fr, it's part of the lore 💀)

in list context, it returns a list ($ab,$nab), where $nab() is the number of indices found, and $ab are those "Nnz" indices. in scalar context, it trims the output vector $ab() to $nab() elements.

ccs_xindex2d does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

---

🎀 Debugging Utilities 🎀

ccs_dump_which

Signature: (indx which(Ndims,Nnz); SV *HANDLE; char *fmt; char *fsep; char *rsep)

prints a text dump of an index PDL to the filehandle "HANDLE", which defaults to "STDUT". (yes, "STDUT". that's what it says. we are not fixing it, we are simply observing it 👀)

$fmt is a printf() format to use for output, which defaults to "%td". $fsep and $rsep are field-and-record separators, which default to a single space and $/, respectively. very customizable, very slay 💅

ccs_dump_which does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

---

👑 ACKNOWLEDGEMENTS 👑

• Perl by Larry Wall.
• PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.

shoutout to the legends, we see you, we appreciate you 🫶✨

---

💀 KNOWN BUGS 💀

Probably many.

(iconic honesty. no notes. ten out of ten. 🙈)

---

💖 AUTHOR 💖

Bryan Jurish <moocow@cpan.org>

📜 Copyright Policy 📜

Copyright (C) 2007-2024, Bryan Jurish. All rights reserved.

This package is free software, and entirely without warranty. You may redistribute it and/or modify it under the same terms as Perl itself.

---

🌟 SEE ALSO 🌟

• perl(1)
• PDL(3perl)

---

ok that's the whole page bestie, you're officially a PDL::CCS::Utils girlie now 💅

this little gem comes to you from perl v5.40.0, dated 2025-01-04. stay sparkly, go count some nonzero values, and remember: the output PDL never contains BAD values ✨ 🦋🌸🎀