Provided by: libpdl-ccs-perl_1.24.1-1_amd64 
NAME
PDL::CCS::Nd - N-dimensional sparse pseudo-PDLs
SYNOPSIS
use PDL;
use PDL::CCS::Nd;
##---------------------------------------------------------------------
## Example data
$missing = 0; ##-- missing values
$dense = random(@dims); ##-- densely encoded pdl
$dense->where(random(@dims)<=0.95) .= $missing; ## ... made sparse
$whichND = $dense->whichND; ##-- which values are present?
$nzvals = $dense->indexND($whichND); ##-- ... and what are they?
##---------------------------------------------------------------------
## Constructors etc.
$ccs = PDL::CCS:Nd->newFromDense($dense,%args); ##-- construct from dense matrix
$ccs = PDL::CCS:Nd->newFromWhich($whichND,$nzvals,%args); ##-- construct from index+value pairs
$ccs = $dense->toccs(); ##-- ensure PDL::CCS::Nd-hood
$ccs = $ccs->toccs(); ##-- ... analogous to PDL::topdl()
$ccs = $dense->toccs($missing,$flags); ##-- ... with optional arguments
$ccs2 = $ccs->copy(); ##-- copy constructor
$ccs2 = $ccs->copyShallow(); ##-- shallow copy, mainly for internal use
$ccs2 = $ccs->shadow(%args); ##-- flexible copy method, for internal use
##---------------------------------------------------------------------
## Maintenance & Decoding
$ccs = $ccs->recode(); ##-- remove missing values from stored VALS
$ccs = $ccs->sortwhich(); ##-- internal use only
$dense2 = $ccs->decode(); ##-- extract to a (new) dense matrix
$dense2 = $ccs->todense(); ##-- ensure dense storage
$dense2 = $dense2->todense(); ##-- ... analogous to PDL::topdl()
##---------------------------------------------------------------------
## PDL API: Basic Properties
##---------------------------------------
## Type conversion & Checking
$ccs2 = $ccs->convert($type);
$ccs2 = $ccs->byte;
$ccs2 = $ccs->short;
$ccs2 = $ccs->ushort;
$ccs2 = $ccs->long;
$ccs2 = $ccs->longlong;
$ccs2 = $ccs->float;
$ccs2 = $ccs->double;
##---------------------------------------
## Dimensions
@dims = $ccs->dims();
$ndims = $ccs->ndims();
$dim = $ccs->dim($dimi);
$nelem = $ccs->nelem;
$bool = $ccs->isnull;
$bool = $ccs->isempty;
##---------------------------------------
## Inplace & Dataflow
$ccs = $ccs->inplace();
$bool = $ccs->is_inplace;
$bool = $ccs->set_inplace($bool);
$ccs = $ccs->sever;
##---------------------------------------
## Bad Value Handling
$bool = $ccs->bad_is_missing(); ##-- treat BAD values as missing?
$bool = $ccs->bad_is_missing($bool);
$ccs = $ccs->badmissing(); ##-- ... a la inplace()
$bool = $ccs->nan_is_missing(); ##-- treat NaN values as missing?
$bool = $ccs->nan_is_missing($bool);
$ccs = $ccs->nanmissing(); ##-- ... a la inplace()
$ccs2 = $ccs->setnantobad();
$ccs2 = $ccs->setbadtonan();
$ccs2 = $ccs->setbadtoval($val);
$ccs2 = $ccs->setvaltobad($val);
##---------------------------------------------------------------------
## PDL API: Dimension Shuffling
$ccs2 = $ccs->dummy($vdimi,$size);
$ccs2 = $ccs->reorder(@vdims);
$ccs2 = $ccs->xchg($vdim1,$vdim2);
$ccs2 = $ccs->mv($vdimFrom,$vdimTo);
$ccs2 = $ccs->transpose();
##---------------------------------------------------------------------
## PDL API: Indexing
$nzi = $ccs->indexNDi($ndi); ##-- guts for indexing methods
$ndi = $ccs->n2oned($ndi); ##-- returns 1d pseudo-index for $ccs
$ivals = $ccs->indexND($ndi);
$ivals = $ccs->index2d($xi,$yi);
$ivals = $ccs->index($flati); ##-- buggy: no pseudo-threading!
$ccs2 = $ccs->dice_axis($vaxis,$vaxis_ix);
$nzi = $ccs->xindex1d($xi); ##-- nz-indices along 0th dimension
$nzi = $ccs->pxindex1d($dimi,$xi); ##-- ... or any dimension, using ptr()
$nzi = $ccs->xindex2d($xi,$yi); ##-- ... or for Cartesian product on 2d matrix
$ccs2 = $ccs->xsubset1d($xi); ##-- subset along 0th dimension
$ccs2 = $ccs->pxsubset1d($dimi,$xi); ##-- ... or any dimension, using ptr()
$ccs2 = $ccs->xsubset2d($xi,$yi); ##-- ... or for Cartesian product on 2d matrix
$whichND = $ccs->whichND();
$vals = $ccs->whichVals(); ##-- like $ccs->indexND($ccs->whichND), but faster
$which = $ccs->which()
$value = $ccs->at(@index);
$ccs = $ccs->set(@index,$value);
##---------------------------------------------------------------------
## PDL API: Ufuncs
$ccs2 = $ccs->prodover;
$ccs2 = $ccs->dprodover;
$ccs2 = $ccs->sumover;
$ccs2 = $ccs->dsumover;
$ccs2 = $ccs->andover;
$ccs2 = $ccs->orover;
$ccs2 = $ccs->bandover;
$ccs2 = $ccs->borover;
$ccs2 = $ccs->maximum;
$ccs2 = $ccs->minimum;
$ccs2 = $ccs->maximum_ind; ##-- -1 indicates "missing" value is maximal
$ccs2 = $ccs->minimum_ind; ##-- -1 indicates "missing" value is minimal
$ccs2 = $ccs->nbadover;
$ccs2 = $ccs->ngoodover;
$ccs2 = $ccs->nnz;
$sclr = $ccs->prod;
$sclr = $ccs->dprod;
$sclr = $ccs->sum;
$sclr = $ccs->dsum;
$sclr = $ccs->nbad;
$sclr = $ccs->ngood;
$sclr = $ccs->min;
$sclr = $ccs->max;
$bool = $ccs->any;
$bool = $ccs->all;
##---------------------------------------------------------------------
## PDL API: Unary Operations (Overloaded)
$ccs2 = $ccs->bitnot; $ccs2 = ~$ccs;
$ccs2 = $ccs->not; $ccs2 = !$ccs;
$ccs2 = $ccs->sqrt;
$ccs2 = $ccs->abs;
$ccs2 = $ccs->sin;
$ccs2 = $ccs->cos;
$ccs2 = $ccs->exp;
$ccs2 = $ccs->log;
$ccs2 = $ccs->log10;
##---------------------------------------------------------------------
## PDL API: Binary Operations (missing is annihilator)
## + $b may be a perl scalar, a dense PDL, or a PDL::CCS::Nd object
## + $c is always returned as a PDL::CCS::Nd ojbect
##---------------------------------------
## Arithmetic
$c = $ccs->plus($b); $c = $ccs1 + $b;
$c = $ccs->minus($b); $c = $ccs1 - $b;
$c = $ccs->mult($b); $c = $ccs1 * $b;
$c = $ccs->divide($b); $c = $ccs1 / $b;
$c = $ccs->modulo($b); $c = $ccs1 % $b;
$c = $ccs->power($b); $c = $ccs1 ** $b;
##---------------------------------------
## Comparisons
$c = $ccs->gt($b); $c = ($ccs > $b);
$c = $ccs->ge($b); $c = ($ccs >= $b);
$c = $ccs->lt($b); $c = ($ccs < $b);
$c = $ccs->le($b); $c = ($ccs <= $b);
$c = $ccs->eq($b); $c = ($ccs == $b);
$c = $ccs->ne($b); $c = ($ccs != $b);
$c = $ccs->spaceship($b); $c = ($ccs <=> $b);
##---------------------------------------
## Bitwise Operations
$c = $ccs->and2($b); $c = ($ccs & $b);
$c = $ccs->or2($b); $c = ($ccs | $b);
$c = $ccs->xor($b); $c = ($ccs ^ $b);
$c = $ccs->shiftleft($b); $c = ($ccs << $b);
$c = $ccs->shiftright($b); $c = ($ccs >> $b);
##---------------------------------------
## Matrix Operations
$c = $ccs->inner($b);
$c = $ccs->matmult($b); $c = $ccs x $b;
$c_dense = $ccs->matmult2d_sdd($b_dense, $zc);
$c_dense = $ccs->matmult2d_zdd($b_dense);
$vnorm = $ccs->vnorm($pdimi);
$vcos = $ccs->vcos_zdd($b_dense);
$vcos = $ccs->vcos_pzd($b_ccs);
##---------------------------------------
## Other Operations
$ccs->rassgn($b); $ccs .= $b;
$str = $ccs->string(); $str = "$ccs";
##---------------------------------------------------------------------
## Indexing Utilities
##---------------------------------------------------------------------
## Low-Level Object Access
$num_v_per_p = $ccs->_ccs_nvperp; ##-- num virtual / num physical
$pdims = $ccs->pdims; $vdims = $ccs->vdims; ##-- physical|virtual dim pdl
$nelem = $ccs->nelem_p; $nelem = $ccs->nelem_v; ##-- physical|virtual nelem
$nstored = $ccs->nstored_p; $nstored = $ccs->nstored_v; ##-- physical|virtual Nnz+1
$nmissing = $ccs->nmissing_p; $nmissing = $ccs->nmissing_v; ##-- physical|virtual nelem-Nnz
$ccs = $ccs->make_physically_indexed(); ##-- ensure all dimensions are physically indexed
$bool = $ccs->allmissing(); ##-- are all values missing?
$missing_val = $ccs->missing; ##-- get missing value
$missing_val = $ccs->missing($missing_val); ##-- set missing value
$ccs = $ccs->_missing($missing_val); ##-- ... returning the object
$whichND_phys = $ccs->_whichND(); ##-- get/set physical indices
$whichND_phys = $ccs->_whichND($whichND_phys);
$nzvals_phys = $ccs->_nzvals(); ##-- get/set physically indexed values
$nzvals_phys = $ccs->_nzvals($vals_phys);
$vals_phys = $ccs->_vals(); ##-- get/set physically indexed values
$vals_phys = $ccs->_vals($vals_phys);
$bool = $ccs->hasptr($pdimi); ##-- check for cached Harwell-Boeing pointer
($ptr,$ptrix) = $ccs->ptr($pdimi); ##-- ... get one, caching for later use
($ptr,$ptrix) = $ccs->getptr($pdimi); ##-- ... compute one, regardless of cache
($ptr,$ptrix) = $ccs->setptr($pdimi,$p,$pix); ##-- ... set a cached pointer
$ccs->clearptr($pdimi); ##-- ... clear a cached pointer
$ccs->clearptrs(); ##-- ... clear all cached pointers
$flags = $ccs->flags(); ##-- get/set object-local flags
$flags = $ccs->flags($flags);
$density = $ccs->density; ##-- get object density
$crate = $ccs->compressionRate; ##-- get compression rate
DESCRIPTION
PDL::CCS::Nd provides an object-oriented implementation of sparse N-dimensional vectors & matrices using
a set of low-level PDLs to encode non-missing values. Currently, only a portion of the PDL API is
implemented.
GLOBALS
The following package-global variables are defined:
Block Size Constants
$BINOP_BLOCKSIZE_MIN = 1;
$BINOP_BLOCKSIZE_MAX = 0;
Minimum (maximum) block size for block-wise incremental computation of binary operations. Zero or undef
indicates no minimum (maximum).
Object Structure
PDL::CCS::Nd object are implemented as perl ARRAY-references. For more intuitive access to object
components, the following package-global variables can be used as array indices to access internal object
structure:
$PDIMS
Indexes a pdl(long,$NPdims) of physically indexed dimension sizes:
$ccs->[$PDIMS]->at($pdim_i) == $dimSize_i
$VDIMS
Indexes a pdl(long,$NVdims) of "virtual" dimension sizes:
$ccs->[$VDIMS]->at($vdim_i) == / -$vdimSize_i if $vdim_i is a dummy dimension
\ $pdim_i otherwise
The $VDIMS piddle is used for dimension-shuffling transformations such as xchg() and reorder(), as
well as for dummy().
$WHICH
Indexes a pdl(long,$NPdims,$Nnz) of the "physical indices" of all non-missing values in the non-dummy
dimensions of the corresponding dense matrix. Vectors in $WHICH are guaranteed to be sorted in
lexicographic order. If your $missing value is zero, and if your qsortvec() function works, it
should be the case that:
all( $ccs->[$WHICH] == $dense->whichND->qsortvec )
A "physically indexed dimension" is just a dimension corresponding tp a single column of the $WHICH
pdl, whereas a dummy dimension does not correspond to any physically indexed dimension.
$VALS
Indexes a vector pdl($valType, $Nnz+1) of all values in the sparse matrix, where $Nnz is the number
of non-missing values in the sparse matrix. Non-final elements of the $VALS piddle are interpreted
as the values of the corresponding indices in the $WHICH piddle:
all( $ccs->[$VALS]->slice("0:-2") == $dense->indexND($ccs->[$WHICH]) )
The final element of the $VALS piddle is referred to as "$missing", and represents the value of all
elements of the dense physical matrix whose indices are not explicitly listed in the $WHICH piddle:
all( $ccs->[$VALS]->slice("-1") == $dense->flat->index(which(!$dense)) )
$PTRS
Indexes an array of arrays containing Harwell-Boeing "pointer" piddle pairs for the corresponding
physically indexed dimension. For a physically indexed dimension $d of size $N, $ccs->[$PTRS][$d]
(if it exists) is a pair [$ptr,$ptrix] as returned by
PDL::CCS::Utils::ccs_encode_pointers($WHICH,$N), which are such that:
$ptr
$ptr is a pdl(long,$N+1) containing the offsets in $ptrix corresponding to the first non-missing
value in the dimension $d. For all $i, 0 <= $i < $N, $ptr($i) contains the index of the first
non-missing value (if any) from column $i of $dense(...,N,...) encoded in the $WHICH piddle.
$ptr($N+1) contains the number of physically indexed cells in the $WHICH piddle.
$ptrix
Is an index piddle into dim(1) of $WHICH rsp. dim(0) of $VALS whose key positions correspond to
the offsets listed in $ptr. The point here is that:
$WHICH->dice_axis(1,$ptrix)
is guaranteed to be primarily sorted along the pointer dimension $d, and stably sorted along all
other dimensions, e.g. should be identical to:
$WHICH->mv($d,0)->qsortvec->mv(0,$d)
$FLAGS
Indexes a perl scalar containing some object-local flags. See "Object Flags" for details.
$USER
Indexes the first unused position in the object array. If you derive a class from PDL::CCS::Nd, you
should use this position to place any new object-local data.
Object Flags
The following object-local constants are defined as bitmask flags:
$CCSND_BAD_IS_MISSING
Bitmask of the "bad-is-missing" flag. See the bad_is_missing() method.
$CCSND_NAN_IS_MISSING
Bitmask of the "NaN-is-missing" flag. See the nan_is_missing() method.
$CCSND_INPLACE
Bitmask of the "inplace" flag. See PDL::Core for details.
$CCSND_FLAGS_DEFAULT
Default flags for new objects.
METHODS
Constructors, etc.
$class_or_obj->newFromDense($dense,$missing,$flags)
Signature ($class_or_obj; dense(N1,...,NNdims); missing(); int flags)
Class method. Create and return a new PDL::CCS::Nd object from a dense N-dimensional PDL $dense. If
specified, $missing is used as the value for "missing" elements, and $flags are used to initialize
the object-local flags.
$missing defaults to BAD if the bad flag of $dense is set, otherwise $missing defaults to zero.
$ccs->fromDense($dense,$missing,$flags)
Signature ($ccs; dense(N1,...,NNdims); missing(); int flags)
Object method. Populate a sparse matrix object from a dense piddle $dense. See newFromDense().
$class_or_obj->newFromWhich($whichND,$nzvals,%options)
Signature ($class_or_obj; int whichND(Ndims,Nnz); nzvals(Nnz+1); %options)
Class method. Create and return a new PDL::CCS::Nd object from a set of indices $whichND of non-
missing elements in a (hypothetical) dense piddle and a vector $nzvals of the corresponding values.
Known %options:
sorted => $bool, ##-- if true, $whichND is assumed to be pre-sorted
steal => $bool, ##-- if true, $whichND and $nzvals are used literally (formerly implied 'sorted')
## + in this case, $nzvals should really be: $nzvals->append($missing)
pdims => $pdims, ##-- physical dimension list; default guessed from $whichND (alias: 'dims')
vdims => $vdims, ##-- virtual dims (default: sequence($nPhysDims)); alias: 'xdims'
missing => $missing, ##-- default: BAD if $nzvals->badflag, 0 otherwise
flags => $flags ##-- flags
$ccs->fromWhich($whichND,$nzvals,%options)
Object method. Guts for newFromWhich().
$a->toccs($missing,$flags)
Wrapper for newFromDense(). Return a PDL::CCS::Nd object for any piddle or perl scalar $a. If $a is
already a PDL::CCS::Nd object, just returns $a. This method gets exported into the PDL namespace for
ease of use.
$ccs = $ccs->copy()
Full copy constructor.
$ccs2 = $ccs->copyShallow()
Shallow copy constructor, used e.g. by dimension-shuffling transformations. Copied components:
$PDIMS, @$PTRS, @{$PTRS->[*]}, $FLAGS
Referenced components:
$VDIMS, $WHICH, $VALS, $PTRS->[*][*]
$ccs2 = $ccs1->shadow(%args)
Flexible constructor for computed PDL::CCS::Nd objects. Known %args:
to => $ccs2, ##-- default: new
pdims => $pdims2, ##-- default: $pdims1->pdl (alias: 'dims')
vdims => $vdims2, ##-- default: $vdims1->pdl (alias: 'xdims')
ptrs => \@ptrs2, ##-- default: []
which => $which2, ##-- default: undef
vals => $vals2, ##-- default: undef
flags => $flags, ##-- default: $flags1
Maintenance & Decoding
$ccs = $ccs->recode()
Recodes the PDL::CCS::Nd object, removing any missing values from its $VALS piddle.
$ccs = $ccs->sortwhich()
Lexicographically sorts $ccs->[$WHICH], altering $VALS accordingly. Clears $PTRS.
$dense = $ccs->decode()
$dense = $ccs->decode($dense)
Decode a PDL::CCS::Nd object to a dense piddle. Dummy dimensions in $ccs should be created as dummy
dimensions in $dense.
$dense = $a->todense()
Ensures that $a is not a PDL::CCS::Nd by wrapping decode(). For PDLs or perl scalars, just returns
$a.
PDL API: Basic Properties
The following basic PDL API methods are implemented and/or wrapped for PDL::CCS::Nd objects:
Type Checking & Conversion
type, convert, byte, short, ushort, long, double
Type-checking and conversion routines are passed on to the $VALS sub-piddle.
Dimension Access
dims, dim, getdim, ndims, getndims, nelem, isnull, isempty
Note that nelem() returns the number of hypothetically addressable cells -- the number of cells in
the corresponding dense matrix, rather than the number of non-missing elements actually stored.
Inplace Operations
set_inplace($bool), is_inplace(), inplace()
Dataflow
sever
Bad Value Handling
setnantobad, setbadtonan, setbadtoval, setvaltobad
See also the bad_is_missing() and nan_is_missing() methods, below.
PDL API: Dimension Shuffling
The following dimension-shuffling methods are supported, and should be compatible to their PDL
counterparts:
dummy($vdimi)
dummy($vdimi, $size)
Insert a "virtual" dummy dimension of size $size at dimension index $vdimi.
reorder(@vdim_list)
Reorder dimensions according to @vdim_list.
xchg($vdim1,$vdim2)
Exchange two dimensions.
mv($vdimFrom, $vdimTo)
Move a dimension to another position, shoving remaining dimensions out of the way to make room.
transpose()
Always copies, unlike xchg(). Also unlike xchg(), works for 1d row-vectors.
PDL API: Indexing
indexNDi($ndi)
Signature: ($ccs; int ndi(NVdims,Nind); int [o]nzi(Nind))
Guts for indexing methods. Given an N-dimensional index piddle $ndi, return a 1d index vector into
$VALS for the corresponding values. Missing values are returned in $nzi as $Nnz == $ccs->_nnz_p;
Uses PDL::VectorValues::vsearchvec() internally, so expect O(Ndims * log(Nnz)) complexity. Although
the theoretical complexity is tough to beat, this method could be made much faster in the usual (read
"sparse") case by an intelligent use of $PTRS if and when available.
indexND($ndi)
index2d($xi,$yi)
Should be mostly compatible to the PDL functions of the same names, but without any boundary
handling.
index($flati)
Implicitly flattens the source pdl. This ought to be fixed.
dice_axis($axis_v, $axisi)
Should be compatible with the PDL function of the same name. Returns a new PDL::CCS::Nd object which
should participate in dataflow.
xindex1d($xi)
Get non-missing indices for any element of $xi along 0th dimension; $xi must be sorted in ascending
order.
pxindex1d($dimi,$xi)
Get non-missing indices for any element of $xi along physically indexed dimension $dimi, using "ptr"
in ptr($dimi). $xi must be sorted in ascending order.
xindex2d($xi,$yi)
Get non-missing indices for any element in Cartesian product ($xi x $yi) for 2d sparse matrix. $xi
and $yi must be sorted in ascending order.
xsubset1d($xi)
Returns a subset object similar to dice_axis(0,$x), but without renumbering of indices along the
diced dimension; $xi must be sorted in ascending order.
pxsubset1d($dimi,$xi)
Returns a subset object similar to dice_axis($dimi,$x), but without renumbering of indices along the
diced dimension; $xi must be sorted in ascending order.
xsubset2d($xi,$yi)
Returns a subset object similar to indexND( $xi->slice("*1,")->cat($yi)->clump(2)->xchg(0,1) ), but
without renumbering of indices; $xi and $yi must be sorted in ascending order.
n2oned($ndi)
Returns a 1d pseudo-index, used for implementation of which(), etc.
whichND()
Should behave mostly like the PDL function of the same name.
Just returns the literal $WHICH piddle if possible: beware of dataflow! Indices are NOT guaranteed
to be returned in any surface-logical order, although physically indexed dimensions should be sorted
in physical-lexicographic order.
whichVals()
Returns $VALS indexed to correspond to the indices returned by whichND(). The only reason to use
whichND() and whichVals() rather than $WHICH and $VALS would be a need for physical representations
of dummy dimension indices: try to avoid it if you can.
which()
As for the builtin PDL function.
at(@index)
Return a perl scalar corresponding to the Nd index @index.
set(@index, $value)
Set a non-missing value at index @index to $value. barf()s if @index points to a missing value.
Ufuncs
The following functions from PDL::Ufunc are implemented, and ought to handle missing values correctly
(i.e. as their dense counterparts would):
prodover
prod
dprodover
dprod
sumover
sum
dsumover
dsum
andover
orover
bandover
borover
maximum
maximum_ind ##-- goofy if "missing" value is maximal
max
minimum
minimum_ind ##-- goofy if "missing" value is minimal
min
nbadover
nbad
ngoodover
ngood
nnz
any
all
Some Ufuncs are still unimplemented. see PDL::CCS::Ufunc for details.
Unary Operations
The following unary operations are supported:
FUNCTION OVERLOADS
bitnot ~
not !
sqrt
abs
sin
cos
exp
log
log10
Note that any pointwise unary operation can be performed directly on the $VALS piddle. You can wrap such
an operation MY_UNARY_OP on piddles into a PDL::CCS::Nd method using the idiom:
package PDL::CCS::Nd;
*MY_UNARY_OP = _unary_op('MY_UNARY_OP', PDL->can('MY_UNARY_OP'));
Note also that unary operations may change the "missing" value associated with the sparse matrix. This
is easily seen to be the Right Way To Do It if you consider unary "not" over a very sparse (say 99%
missing) binary-valued matrix: is is much easier and more efficient to alter only the 1% of physically
stored (non-missing) values as well as the missing value than to generate a new matrix with 99% non-
missing values, assuming $missing==0.
Binary Operations
A number of basic binary operations on PDL::CCS::Nd operations are supported, which will produce correct
results only under the assumption that "missing" values $missing are annihilators for the operation in
question. For example, if we want to compute:
$c = OP($a,$b)
for a binary operation OP on PDL::CCS::Nd objects $a and $b, the current implementation will produce the
correct result for $c only if for all values $av in $a and $bv in $b:
OP($av,$b->missing) == OP($a->missing,$b->missing) , and
OP($a->missing,$bv) == OP($a->missing,$b->missing)
This is true in general for OP==\&mult and $missing==0, but not e.g. for OP==\&plus and $missing==0. It
should always hold for $missing==BAD (except in the case of assignment, which is a funny kind of
operation anyways).
Currently, the only way to ensure that all values are computed correctly in the general case is for $a
and $b to contain exactly the same physically indexed values, which rather defeats the purposes of sparse
storage, particularly if implicit pseudo-threading is involved (because then we would likely wind up
instantiating -- or at least inspecting -- the entire dense matrix). Future implementations may relax
these restrictions somewhat.
The following binary operations are implemented:
Arithmetic Operations
FUNCTION OVERLOADS
plus +
minus -
mult *
divide /
modulo %
power **
Comparisons
FUNCTION OVERLOADS
gt >
ge >=
lt <
le <=
eq ==
ne !=
spaceship <=>
Bitwise Operations
FUNCTION OVERLOADS
and2 &
or2 |
xor ^
shiftleft <<
shiftright >>
Matrix Operations
FUNCTION OVERLOADS
inner (none)
matmult x
Other Operations
FUNCTION OVERLOADS
rassgn .=
string ""
All supported binary operation functions obey the PDL input calling conventions (i.e. they all accept a
third argument $swap), and delegate computation to the underlying PDL functions. Note that the
PDL::CCS::Nd methods currently do NOT support a third "output" argument. To wrap a new binary operation
MY_BINOP into a PDL::CCS::Nd method, you can use the following idiom:
package PDL::CCS::Nd;
*MY_BINOP = _ccsnd_binary_op_mia('MY_BINOP', PDL->can('MY_BINOP'));
The low-level alignment of physically indexed values for binary operations is performed by the function
PDL::CCS::ccs_binop_align_block_mia(). Computation is performed block-wise at the perl level to avoid
over- rsp. underflow of the space requirements for the output PDL.
Low-Level Object Access
The following methods provide low-level access to PDL::CCS::Nd object structure:
insertWhich
Signature: ($ccs; int whichND(Ndims,Nnz1); vals(Nnz1))
Set or insert values in $ccs for the indices in $whichND to $vals. $whichND need not be sorted.
Implicitly makes $ccs physically indexed. Returns the (destructively altered) $ccs.
appendWhich
Signature: ($ccs; int whichND(Ndims,Nnz1); vals(Nnz1))
Like insertWhich(), but assumes that no values for any of the $whichND indices are already present in
$ccs. This is faster (because indexNDi need not be called), but less safe.
is_physically_indexed()
Returns true iff only physical dimensions are present.
to_physically_indexed()
Just returns the calling object if all non-missing elements are already physically indexed.
Otherwise, returns a new PDL::CCS::Nd object identical to the caller except that all non-missing
elements are physically indexed. This may gobble a large amount of memory if the calling element has
large dummy dimensions. Also ensures that physical dimension order is identical to logical dimension
order.
make_physically_indexed
Wrapper for to_physically_indexed() which eliminates dummy dimensions destructively in the calling
object.
Alias: make_physical().
pdims()
Returns the $PDIMS piddle. See "Object Structure", above.
vdims()
Returns the $VDIMS piddle. See "Object Structure", above.
setdims_p(@dims)
Sets $PDIMS piddle. See "Object Structure", above. Returns the calling object. Alias: setdims().
nelem_p()
Returns the number of physically addressable elements.
nelem_v()
Returns the number of virtually addressable elements. Alias for nelem().
_ccs_nvperp()
Returns number of virtually addressable elements per physically addressable element, which should be
a positive integer.
nstored_p()
Returns actual number of physically addressed stored elements (aka $Nnz aka $WHICH->dim(1)).
nstored_v()
Returns actual number of physically+virtually addressed stored elements.
nmissing_p()
Returns number of physically addressable elements minus the number of physically stored elements.
nmissing_v()
Returns number of physically+virtually addressable elements minus the number of physically+virtually
stored elements.
allmissing()
Returns true iff no non-missing values are stored.
missing()
missing($missing)
Get/set the value to use for missing elements. Returns the (new) value for $missing.
_whichND()
_whichND($whichND)
Get/set the underlying $WHICH piddle.
_nzvals()
_nzvals($storedvals)
Get/set the slice of the underlying $VALS piddle corresponding for non-missing values only. Alias:
whichVals().
_vals()
_vals($storedvals)
Get/set the underlying $VALS piddle.
hasptr($pdimi)
Returns true iff a pointer for physical dim $pdimi is cached.
ptr($pdimi)
Get a pointer pair for a physically indexed dimension $pdimi. Uses cached piddles in $PTRS if
present, computes & caches otherwise.
$pdimi defaults to zero. If $pdimi is zero, then it should hold that:
all( $pi2nzi==sequence($ccs->nstored_p) )
getptr($pdimi)
Guts for ptr(). Does not check $PTRS and does not cache anything.
clearptr($pdimi)
Clears any cached Harwell-Boeing pointers for physically indexed dimension $pdimi.
clearptrs()
Clears any cached Harwell-Boeing pointers.
flags()
flags($flags)
Get/set object-local $FLAGS.
bad_is_missing()
bad_is_missing($bool)
Get/set the value of the object-local "bad-is-missing" flag. If this flag is set, BAD values in
$VALS are considered "missing", regardless of the current value of $missing.
badmissing()
Sets the "bad-is-missing" flag and returns the calling object.
nan_is_missing()
nan_is_missing($bool)
Get/set the value of the object-local "NaN-is-missing" flag. If this flag is set, NaN (and +inf,
-inf) values in $VALS are considered "missing", regardless of the current value of $missing.
nanmissing()
Sets the "nan-is-missing" flag and returns the calling object.
General Information
density()
Returns the number of non-missing values divided by the number of indexable values in the sparse
object as a perl scalar.
compressionRate()
Returns the compression rate of the PDL::CCS::Nd object compared to a dense piddle of the physically
indexable dimensions. Higher values indicate better compression (e.g. lower density). Negative
values indicate that dense storage would be more memory-efficient. Pointers are not included in the
computation of the compression rate.
ACKNOWLEDGEMENTS
Perl by Larry Wall.
PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
KNOWN BUGS
Many.
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), PDL::SVDLIBC(3perl), PDL::CCS::Nd(3perl),
SVDLIBC: http://tedlab.mit.edu/~dr/SVDLIBC/
SVDPACKC: http://www.netlib.org/svdpack/
perl v5.40.0 2025-01-04 Nd(3pm)