.\" 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 "Functions 3pm"
.TH Functions 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::Functions \- Useful perl\-level functions for PDL::CCS
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use PDL;
\& use PDL::CCS::Functions;
\&
\& ##\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ## ... stuff happens
.Ve
.SH "Decoding"
.IX Header "Decoding"
.SS "ccs_pointerlen"
.IX Subsection "ccs_pointerlen"
.Vb 1
\&  Signature: (indx ptr(N+1); indx [o]len(N))
.Ve
.PP
Get number of non-missing values for each axis value from a CCS-encoded
offset pointer vector $\fBptr()\fR.
.SS "ccs_decode"
.IX Subsection "ccs_decode"
.Vb 1
\&  Signature: (indx whichnd(Ndims,Nnz); nzvals(Nnz); missing(); \e@Dims; [o]a(@Dims))
.Ve
.PP
Decode a CCS-encoded matrix (no dataflow).
.SH "Scalar Operations"
.IX Header "Scalar Operations"
Scalar operations can be performed in parallel directly on \f(CW$nzvals\fR
(and if applicable on \f(CW$missing\fR as well):
.PP
.Vb 1
\& $c = 42;
\&
\& $nzvals2 = $nzvals  + $c;        $missing2 = $missing  + $c;
\& $nzvals2 = $nzvals  \- $c;        $missing2 = $missing  \- $c;
\& $nzvals2 = $nzvals  * $c;        $missing2 = $missing  * $c;
\& $nzvals2 = $nzvals  / $c;        $missing2 = $missing  / $c;
\&
\& $nzvals2 = $nzvals ** $c;        $missing2 = $missing ** $c;
\& $nzvals2 = log($nzvals);         $missing2 = log($missing);
\& $nzvals2 = exp($nzvals);         $missing2 = exp(missing);
\&
\& $nzvals2 = $nzvals\->and2($c,0);  $missing2 = $missing\->and($c,0);
\& $nzvals2 = $nzvals\->or2($c,0);   $missing2 = $missing\->or2($c,0);
\& $nzvals2 = $nzvals\->not();       $missing2 = $missing\->not();
.Ve
.PP
Nothing prevents scalar operations from producing new \*(L"missing\*(R" values (e.g. \f(CW$nzvals\fR*0),
so you might want to re-encode your compressed data after applying the operation.
.SH "Vector Operations"
.IX Header "Vector Operations"
.SS "ccs_OP_vector_mia"
.IX Subsection "ccs_OP_vector_mia"
.Vb 1
\&  Signature: (indx whichDimV(Nnz); nzvals(Nnz); vec(V); [o]nzvals_out(Nnz))
.Ve
.PP
A number of row\- and column-vector operations may be performed directly
on encoded Nd-PDLs, without the need for decoding to a (potentially huge)
dense temporary.  These operations assume that \*(L"missing\*(R" values are
annihilators with respect to the operation in question, i.e.
that it holds for all \f(CW$x\fR in \f(CW$vec\fR that:
.PP
.Vb 1
\& ($missing _\|_OP_\|_ $x) == $missing
.Ve
.PP
This is in line with the usual \s-1PDL\s0 semantics if your \f(CW$missing\fR value is \f(CW\*(C`BAD\*(C'\fR,
but may produce unexpected results when e.g. adding a vector to a sparse \s-1PDL\s0 with \f(CW$missing\fR==0.
If you really need to do something like the latter, then you're probably better off decoding to
a dense \s-1PDL\s0 anyway.
.PP
Predefined function names for encoded-PDL vector operations are all of the form:
\&\f(CW\*(C`ccs_${OPNAME}_ma\*(C'\fR, where ${\s-1OPNAME\s0} is the base name of the operation:
.PP
.Vb 6
\& plus       ##\-\- addition
\& minus      ##\-\- subtraction
\& mult       ##\-\- multiplication (NOT matrix\-multiplication)
\& divide     ##\-\- division
\& modulo     ##\-\- modulo
\& power      ##\-\- potentiation
\&
\& gt         ##\-\- greater\-than
\& ge         ##\-\- greater\-than\-or\-equal
\& lt         ##\-\- less\-than
\& le         ##\-\- less\-than\-or\-equal
\& eq         ##\-\- equality
\& ne         ##\-\- inequality
\& spaceship  ##\-\- 3\-way comparison
\&
\& and2       ##\-\- binary AND
\& or2        ##\-\- binary OR
\& xor        ##\-\- binary XOR
\& shiftleft  ##\-\- left\-shift
\& shiftright ##\-\- right\-shift
.Ve
.SS "\e&CODE = ccs_binop_vector_mia($opName, \e&PDLCODE);"
.IX Subsection "&CODE = ccs_binop_vector_mia($opName, &PDLCODE);"
Returns a generic vector-operation subroutine which reports errors as \f(CW$opName\fR
and uses \e&PDLCODE to perform underlying computation.
.SH "Sorting"
.IX Header "Sorting"
.SS "ccs_qsort"
.IX Subsection "ccs_qsort"
.Vb 1
\&  Signature: (indx which(Ndims,Nnz); nzvals(Nnz); missing(); Dim0(); indx [o]nzix(Nnz); indx [o]nzenum(Nnz))
.Ve
.PP
Underlying guts for \fBPDL::CCS::Nd::qsort()\fR and \fBPDL::CCS::Nd::qsorti()\fR.
Given a set of \f(CW$Nnz\fR items \f(CW$i\fR each associated with a vector-key \f(CW\*(C`$which(:,$i)\*(C'\fR
and a value \f(CW\*(C`$nzvals($i)\*(C'\fR, returns a vector of \f(CW$Nnz\fR item indices \f(CW\*(C`$nzix()\*(C'\fR
such that \f(CW\*(C`$which(:,$nzix)\*(C'\fR is vector-sorted in ascending order and
\&\f(CW\*(C`$nzvals(:,$nzix)\*(C'\fR are sorted in ascending order for each unique key-vector in
\&\f(CW\*(C`$which()\*(C'\fR, and an enumeration \f(CW\*(C`$nzenum()\*(C'\fR of items for each unique key-vector
in terms of the sorted data: \f(CW\*(C`$nzenum($j)\*(C'\fR is the logical position of the item
\&\f(CW\*(C`$nzix($j)\*(C'\fR.
.PP
If \f(CW$missing\fR and \f(CW$Dim0\fR are defined,
items \f(CW\*(C`$i=$nzix($j)\*(C'\fR with values \f(CW\*(C`$nzvals($i) > $missing\*(C'\fR
will be logically enumerated at the end of the range [0,$Dim0\-1]
and there will be a gap between \f(CW\*(C`$nzenum()\*(C'\fR values for a \f(CW\*(C`$which()\*(C'\fR\-key
with fewer than \f(CW$Dim0\fR instances; otherwise $\fBnzenum()\fR values will be
enumerated in ascending order starting from 0.
.PP
For an unsorted index+value dataset \f(CW\*(C`($which0,$nzvals0)\*(C'\fR with
.PP
.Vb 1
\& ($nzix,$nzenum) = ccs_qsort($which0("1:\-1,"),$nzvals0,$missing,$which0("0,")\->max+1)
.Ve
.PP
\&\fBqsort()\fR can be implemented as:
.PP
.Vb 2
\& $which  = $nzenum("*1,")\->glue(0,$which0("1:\-1,")\->dice_axis(1,$nzix));
\& $nzvals = $nzvals0\->index($nzix);
.Ve
.PP
and \fBqsorti()\fR as:
.PP
.Vb 2
\& $which  = $nzenum("*1,")\->glue(0,$which0("1:\-1,")\->dice_axis(1,$nzix));
\& $nzvals = $which0("(0),")\->index($nzix);
.Ve
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Perl by Larry Wall.
.PP
\&\s-1PDL\s0 by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
.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),
\&\fBPDL::CCS::Nd\fR\|(3perl),