.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Utils 3pm"
.TH Utils 3pm "2022-12-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::CCS::Utils \- Low\-level utilities for compressed storage sparse PDLs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use PDL;
\& use PDL::CCS::Utils;
\&
\& ##\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ## ... stuff happens
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SH "Non-missing Value Counts"
.IX Header "Non-missing Value Counts"
.SS "nnz"
.IX Subsection "nnz"
.Vb 1
\&  Signature: (a(N); int+ [o]nnz())
.Ve
.PP
Get number of non-zero values in a \s-1PDL\s0 $a();
For 1d PDLs, should be equivalent to:
.PP
.Vb 1
\& $nnz = nelem(which($a!=0));
.Ve
.PP
For k>1 dimensional PDLs, projects via number of nonzero elements
to N\-1 dimensions by computing the number of nonzero elements
along the the 1st dimension.
.PP
nnz 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.
.SS "nnza"
.IX Subsection "nnza"
.Vb 1
\&  Signature: (a(N); eps(); int+ [o]nnz())
.Ve
.PP
Like \fBnnz()\fR using tolerance constant $\fBeps()\fR.
For 1d PDLs, should be equivalent to:
.PP
.Vb 1
\& $nnz = nelem(which(!$a\->approx(0,$eps)));
.Ve
.PP
nnza 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.
.SH "Encoding Utilities"
.IX Header "Encoding Utilities"
.SS "ccs_encode_pointers"
.IX Subsection "ccs_encode_pointers"
.Vb 1
\&  Signature: (indx ix(Nnz); indx N(); indx [o]ptr(Nplus1); indx [o]ixix(Nnz))
.Ve
.PP
General \s-1CCS\s0 encoding utility.
.PP
Get a compressed storage \*(L"pointer\*(R" vector \f(CW$ptr\fR
for a dimension of size \f(CW$N\fR with non-missing values at indices \f(CW$ix\fR.  Also returns a vector
$\fBixix()\fR which may be used as an index for $\fBix()\fR to align its elements with $\fBptr()\fR
along the compressed dimension.
.PP
The induced vector \f(CW$ix\fR\->index($ixix) is
guaranteed to be stably sorted along dimension $N():
.PP
.Vb 1
\& \eforall $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
.Ve
.PP
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.
.SH "Decoding Utilities"
.IX Header "Decoding Utilities"
.SS "ccs_decode_pointer"
.IX Subsection "ccs_decode_pointer"
.Vb 1
\&  Signature: (indx ptr(Nplus1); indx proj(Nproj); indx [o]projix(NnzProj); indx [o]nzix(NnzProj))
.Ve
.PP
General \s-1CCS\s0 decoding utility.
.PP
Project indices $\fBproj()\fR from a compressed storage \*(L"pointer\*(R" vector $\fBproj()\fR.
If unspecified, $\fBproj()\fR defaults to:
.PP
.Vb 1
\& sequence($ptr\->dim(0))
.Ve
.PP
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.
.SS "ccs_pointerlen"
.IX Subsection "ccs_pointerlen"
.Vb 1
\&  Signature: (ptr(Nplus1); [o]ptrlen(N))
.Ve
.PP
Get number of non-missing values for each axis value from a CCS-encoded
offset pointer vector $\fBptr()\fR.
.PP
ccs_pointerlen 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.
.SH "Indexing Utilities"
.IX Header "Indexing Utilities"
.SS "ccs_xindex1d"
.IX Subsection "ccs_xindex1d"
.Vb 1
\&  Signature: (which(Ndims,Nnz); a(Na); [o]nzia(NnzA); [o]nnza())
.Ve
.PP
Compute indices $\fBnzai()\fR along dimension \f(CW\*(C`NNz\*(C'\fR of $\fBwhich()\fR whose initial values \f(CW$whic\fRh(0,$nzai)
match some element of $a().  Appropriate for indexing a sparse encoded \s-1PDL\s0
with non-missing entries at $\fBwhich()\fR
along the 0th dimension, a la dice_axis(0,$a).
\&\f(CW$whic\fRh((0),) and $a() must be both sorted in ascending order.
.PP
In list context, returns a list ($nzai,$nnza), where $\fBnnza()\fR is the number of indices found,
and \f(CW$nzai\fR are those \f(CW\*(C`Nnz\*(C'\fR indices.  In scalar context, trims the output vector $\fBnzai()\fR to $\fBnnza()\fR
elements.
.PP
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.
.SS "ccs_xindex2d"
.IX Subsection "ccs_xindex2d"
.Vb 1
\&  Signature: (which(Ndims,Nnz); a(Na); b(Nb); [o]ab(Nab); [o]nab())
.Ve
.PP
Compute indices along dimension \f(CW\*(C`NNz\*(C'\fR of $\fBwhich()\fR corresponding to any combination
of values in the Cartesian product of $a() and $b().  Appropriate for indexing a
2d sparse encoded \s-1PDL\s0 with non-missing entries at $\fBwhich()\fR via the ND-index piddle
\&\f(CW$a\fR\->slice(\*(L"*1,\*(R")\->cat($b)\->\fBclump\fR\|(2)\->xchg(0,1), i.e. all pairs \f(CW$ai\fR,$bi with \f(CW$ai\fR in $a()
and \f(CW$bi\fR in $b().  $a() and $b() values must be be sorted in ascending order
.PP
In list context, returns a list ($ab,$nab), where $\fBnab()\fR is the number of indices found,
and \f(CW$ab\fR are those \f(CW\*(C`Nnz\*(C'\fR indices.  In scalar context, trims the output vector $\fBab()\fR to $\fBnab()\fR
elements.
.PP
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.
.SH "Debugging Utilities"
.IX Header "Debugging Utilities"
.SS "ccs_dump_which"
.IX Subsection "ccs_dump_which"
.Vb 1
\&  Signature: (indx which(Ndims,Nnz); SV *HANDLE; char *fmt; char *fsep; char *rsep)
.Ve
.PP
Print a text dump of an index \s-1PDL\s0 to the filehandle \f(CW\*(C`HANDLE\*(C'\fR, which default to \f(CW\*(C`STDUT\*(C'\fR.
\&\f(CW$fmt\fR is a \fBprintf()\fR format to use for output, which defaults to \*(L"%d\*(R".
\&\f(CW$fsep\fR and \f(CW$rsep\fR are field-and record separators, which default to
a single space and \f(CW$/\fR, respectively.
.PP
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.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Perl by Larry Wall.
.PP
\&\s-1PDL\s0 by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
Probably many.
.SH "AUTHOR"
.IX Header "AUTHOR"
Bryan Jurish <moocow@cpan.org>
.SS "Copyright Policy"
.IX Subsection "Copyright Policy"
Copyright (C) 2007\-2022, Bryan Jurish. All rights reserved.
.PP
This package is free software, and entirely without warranty.
You may redistribute it and/or modify it under the same terms
as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \s-1\fBPDL\s0\fR\|(3perl)