ccs_binop_align_block_mia

  Signature: (
    indx ixa(Ndims,NnzA); indx ixb(Ndims,NnzB); indx    istate(State);
    indx [o]nzai(NnzC);   indx [o]nzbi(NnzC);   indx [o]ostate(State);
    )

Partially aligns a pair of lexicographically sorted index-vector lists "$ixa()" and "$ixb()", e.g. for block-wise incremental computation of binary operations over sparse index-encoded PDLs, assuming missing indices correspond to annihilators.

On return, the vectors $nzai and $nzbi hold indices into "NnzA" and "NnzB" respectively, and are constructed such that:

 ($ixa(,$nzai->slice("0:$nzci_max")) == $ixb(,$nzbi->slice("0:$nzci_max"))

At most "NnzC" alignments are performed, and alignment ceases as soon as any of the PDLs "$ixa()", "$ixb()", "$nzai()", or "$nzbi()" has been exhausted.

The parameters "$istate()" and "$ostate()" hold the state of the algorithm, for incremental block-wise computation at the perl level. Each state PDL is a 7-element PDL containing the following values:

 INDEX LABEL       DESCRIPTION
 -----------------------------------------------------------------------
   0   nnzai       minimum offset in NnzA of current $ixa() value
   1   nnzai_nxt   minimum offset in NnzA of next $ixa() value
   2   nnzbi       minimum offset in NnzB of current $ixb() value
   3   nnzbi_nxt   minimum offset in NnzB of next $ixb() value
   4   nnzci       minimum offset in NnzC of current ($ixa(),$ixb()) value pair
   5   nnzci_nxt   minimum offset in NnzC of next ($ixa(),$ixb()) value pair
   6   cmpval      3-way comparison value for current ($ixa(),$ixb()) value pair

For computation of the first block, $istate() can be safely set to "zeroes(long,7)".

Repetitions may occur in input index PDLs "$ixa()" and "$ixb()". If an index-match occurs on such a "run", all pairs of matching values are added to the output PDLs.

All alignments have been performed if:

 $ostate(0)==$NnzA && $ostate(1)==$NnzB

WARNING: this alignment method ignores index-vectors which are not present in both "$ixa()" and "$ixb()", which is a Good Thing if your are feeding the aligned values into an operation for which missing values are annihilators:

 $missinga * $bval     == ($missinga * $missingb)  for each $bval \in $b, and
 $aval     * $missingb == ($missinga * $missingb)  for each $aval \in $a

This ought to be the case for all operations if missing values are "BAD" (see PDL::Bad), but might cause unexpected results if e.g. missing values are zero and the operation in question is addition.

ccs_binop_align_block_mia 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.

Copyright Policy

All other parts Copyright (C) 2007-2022, 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.