---
name: "PDL::CCS::Utils"
section: "3pm"
platform: "linux"
package: "libpdl-ccs-perl"
version: "1.24.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/PDL::CCS::Utils"
---

# PDL::CCS::Utils(3pm)

Low-level utilities for compressed storage sparse PDLs

## NAME

PDL::CCS::Utils - Low-level utilities for compressed storage sparse PDLs

## SYNOPSIS

```
 use PDL;
 use PDL::CCS::Utils;
 ##---------------------------------------------------------------------
 ## ... stuff happens
```

## FUNCTIONS

## Non-missing Value Counts

### nnz

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

Get number of non-zero values in a PDL $a(); For 1d PDLs, should be equivalent to:

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

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.

The output PDL $**nnz()** never contains BAD values.

### nnza

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

Like **nnz()** using tolerance constant $**eps()**. For 1d PDLs, should be equivalent to:

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

The output PDL $**nnz()** never contains BAD values.

## Encoding Utilities

### ccs\_encode\_pointers

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

General CCS encoding utility.

Get a compressed storage "pointer" vector `$ptr` for a dimension of size `$N` with non-missing values at indices `$ix`.  Also returns a vector $**ixix()** which may be used as an index for $**ix()** to align its elements with $**ptr()** along the compressed dimension.

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.

## Decoding Utilities

### ccs\_decode\_pointer

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

General CCS decoding utility.

Project indices $**proj()** from a compressed storage "pointer" vector $**ptr()**. If unspecified, $**proj()** 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.

## Indexing Utilities

### ccs\_xindex1d

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

Compute indices $**nzai()** along dimension `"Nnz"` of $**which()** whose initial values `$whic`h(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). `$whic`h((0),) and $a() must be both sorted in ascending order.

In list context, returns a list ($nzai,$nnza), where $**nnza()** is the number of indices found, and `$nzai` are those `"Nnz"` indices.  In scalar context, trims the output vector $**nzai()** to $**nnza()** elements.

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())
```

Compute 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().  $a() and $b() values must be be sorted in ascending order

In list context, returns a list ($ab,$nab), where $**nab()** is the number of indices found, and `$ab` are those `"Nnz"` indices.  In scalar context, 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)
```

Print a text dump of an index PDL to the filehandle `"HANDLE"`, which default to `"STDUT"`. `$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.

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.

## KNOWN BUGS

Probably 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)](/perl/1.md), **PDL**(3perl)