NAME
PDL::Primitive - primitive operations for pdl
DESCRIPTION
This module provides some primitive and useful functions defined using PDL::PP and able to use the new indexing tricks.
See PDL::Indexing for how to use indices creatively. For explanation of the signature format, see PDL::PP.
SYNOPSIS
# Pulls in PDL::Primitive, among other modules.
use PDL;
# Only pull in PDL::Primitive:
use PDL::Primitive;Inner product over one dimension
c = sum_i a_i * b_iSee also "norm", "magnover" in PDL::Ufunc. ', BadDoc => ' If a() * b() contains only bad data, c() is set bad. Otherwise c() will have its bad flag cleared, as it will not contain any bad values. ', ); # pp_def( inner )
pp_def('outer', HandleBad => 1, Pars => 'a(n); b(m); [o]c(n,m);', GenericTypes => [ppdefs_all], Code => <<'EOF', loop(n,m) %{ PDL_IF_BAD(if ( $ISBAD(a()) || $ISBAD(b()) ) { $SETBAD(c()); continue; },) $c() = $a() * $b(); %} EOF Doc => ' =for ref
outer product over one dimension
Naturally, it is possible to achieve the effects of outer product simply by broadcasting over the "*" operator but this function is provided for convenience. '); # pp_def( outer )
pp_addpm(<<'EOD'); =head2 x
Signature: (a(i,z), b(x,i),[o]c(x,z))Matrix multiplication
PDL overloads the x operator (normally the repeat operator) for matrix multiplication. The number of columns (size of the 0 dimension) in the left-hand argument must normally equal the number of rows (size of the 1 dimension) in the right-hand argument.
Row vectors are represented as (N x 1) two-dimensional PDLs, or you may be sloppy and use a one-dimensional PDL. Column vectors are represented as (1 x N) two-dimensional PDLs.
Broadcasting occurs in the usual way, but as both the 0 and 1 dimension (if present) are included in the operation, you must be sure that you don't try to broadcast over either of those dims.
Of note, due to how Perl v5.14.0 and above implement operator overloading of the x operator, the use of parentheses for the left operand creates a list context, that is
pdl> ( $x * $y ) x $z
ERROR: Argument "..." isn't numeric in repeat (x) ...treats $z as a numeric count for the list repeat operation and does not call the scalar form of the overloaded operator. To use the operator in this case, use a scalar context:
pdl> scalar( $x * $y ) x $zor by calling "matmult" directly:
pdl> ( $x * $y )->matmult( $z )EXAMPLES
Here are some simple ways to define vectors and matrices:
pdl> $r = pdl(1,2); # A row vector
pdl> $c = pdl([[3],[4]]); # A column vector
pdl> $c = pdl(3,4)->(*1); # A column vector, using NiceSlice
pdl> $m = pdl([[1,2],[3,4]]); # A 2x2 matrixNow that we have a few objects prepared, here is how to matrix-multiply them:
pdl> print $r x $m # row x matrix = row
[
[ 7 10]
]
pdl> print $m x $r # matrix x row = ERROR
PDL: Dim mismatch in matmult of [2x2] x [2x1]: 2 != 1
pdl> print $m x $c # matrix x column = column
[
[ 5]
[11]
]
pdl> print $m x 2 # Trivial case: scalar mult.
[
[2 4]
[6 8]
]
pdl> print $r x $c # row x column = scalar
[
[11]
]
pdl> print $c x $r # column x row = matrix
[
[3 6]
[4 8]
]INTERNALS
The mechanics of the multiplication are carried out by the "matmult" method.
Matrix multiplication
Notionally, matrix multiplication $x x $y is equivalent to the broadcasting expression
$x->dummy(1)->inner($y->xchg(0,1)->dummy(2),$c);but for large matrices that breaks CPU cache and is slow. Instead, matmult calculates its result in 32x32x32 tiles, to keep the memory footprint within cache as long as possible on most modern CPUs.
For usage, see "x", a description of the overloaded 'x' operator
EOD );
pp_def('innerwt', HandleBad => 1, Pars => 'a(n); b(n); c(n); [o]d();', GenericTypes => [ppdefs_all], Code => <<'EOF', complex long double tmp = 0; PDL_IF_BAD(int flag = 0;,) loop(n) %{ PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,) tmp += $a() * $b() * $c(); %} PDL_IF_BAD(if (!flag) { $SETBAD(d()); } else,) { $d() = tmp; } EOF Doc => '
Weighted (i.e. triple) inner product
d = sum_i a(i) b(i) c(i)
'
);pp_def('inner2', HandleBad => 1, Pars => 'a(n); b(n,m); c(m); [o]d();', GenericTypes => [ppdefs_all], Code => <<'EOF', complex long double tmp = 0; PDL_IF_BAD(int flag = 0;,) loop(n,m) %{ PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,) tmp += $a() * $b() * $c(); %} PDL_IF_BAD(if (!flag) { $SETBAD(d()); } else,) { $d() = tmp; } EOF Doc => ' =for ref
Inner product of two vectors and a matrix
d = sum_ij a(i) b(i,j) c(j)Note that you should probably not broadcast over a and c since that would be very wasteful. Instead, you should use a temporary for b*c. ' );
pp_def('inner2d', HandleBad => 1, Pars => 'a(n,m); b(n,m); [o]c();', GenericTypes => [ppdefs_all], Code => <<'EOF', complex long double tmp = 0; PDL_IF_BAD(int flag = 0;,) loop(n,m) %{ PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b())) continue;flag = 1;,) tmp += $a() * $b(); %} PDL_IF_BAD(if (!flag) { $SETBAD(c()); } else,) { $c() = tmp; } EOF Doc => ' =for ref
Inner product over 2 dimensions.
Equivalent to
$c = inner($x->clump(2), $y->clump(2))
'
);pp_def('inner2t', HandleBad => 1, Pars => 'a(j,n); b(n,m); c(m,k); [t]tmp(n,k); [o]d(j,k);', GenericTypes => [ppdefs_all], Code => <<'EOF', loop(n,k) %{ complex long double tmp0 = 0; PDL_IF_BAD(int flag = 0;,) loop(m) %{ PDL_IF_BAD(if ($ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,) tmp0 += $b() * $c(); %} PDL_IF_BAD(if (!flag) { $SETBAD(tmp()); } else,) { $tmp() = tmp0; } %} loop(j,k) %{ complex long double tmp1 = 0; PDL_IF_BAD(int flag = 0;,) loop(n) %{ PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(tmp())) continue;flag = 1;,) tmp1 += $a() * $tmp(); %} PDL_IF_BAD(if (!flag) { $SETBAD(d()); } else,) { $d() = tmp1; } %} EOF Doc => ' =for ref
Efficient Triple matrix product a*b*c
Efficiency comes from by using the temporary tmp. This operation only scales as N**3 whereas broadcasting using "inner2" would scale as N**4.
The reason for having this routine is that you do not need to have the same broadcast-dimensions for tmp as for the other arguments, which in case of large numbers of matrices makes this much more memory-efficient.
It is hoped that things like this could be taken care of as a kind of closure at some point. ' ); # pp_def inner2t()
# a helper function for the cross product definition sub crassgn { "\$c(tri => $_[0]) = \$a(tri => $_[1])*\$b(tri => $_[2]) - \$a(tri => $_[2])*\$b(tri => $_[1]);" }
pp_def('crossp', Doc => <<'EOD', =for ref
Cross product of two 3D vectors
After
$c = crossp $x, $ythe inner product $c*$x and $c*$y will be zero, i.e. $c is orthogonal to $x and $y EOD Pars => 'a(tri=3); b(tri); [o] c(tri)', GenericTypes => [ppdefs_all], Code => crassgn(0,1,2)."\n". crassgn(1,2,0)."\n". crassgn(2,0,1), );
pp_def('norm', HandleBad => 1, Pars => 'vec(n); [o] norm(n)', GenericTypes => [ppdefs_all], Doc => 'Normalises a vector to unit Euclidean length
See also "inner", "magnover" in PDL::Ufunc. ', Code => <<'EOF', long double sum=0; PDL_IF_BAD(int flag = 0;,) loop(n) %{ PDL_IF_BAD(if ($ISBAD(vec())) continue; flag = 1;,) sum += PDL_IF_GENTYPE_REAL( $vec()*$vec(), creall($vec())*creall($vec()) + cimagl($vec())*cimagl($vec()) ); %} PDL_IF_BAD(if ( !flag ) { loop(n) %{ $SETBAD(norm()); %} continue; },) if (sum > 0) { sum = sqrtl(sum); loop(n) %{ PDL_IF_BAD(if ( $ISBAD(vec()) ) { $SETBAD(norm()); } else ,) { $norm() = $vec()/sum; } %} } else { loop(n) %{ PDL_IF_BAD(if ( $ISBAD(vec()) ) { $SETBAD(norm()); } else ,) { $norm() = $vec(); } %} } EOF );
# this one was motivated by the need to compute # the circular mean efficiently # without it could not be done efficiently or without # creating large intermediates (check pdl-porters for # discussion) # see PDL::ImageND for info about the circ_mean function
pp_def( 'indadd', HandleBad => 1, Pars => 'input(n); indx ind(n); [io] sum(m)', GenericTypes => [ppdefs_all], Code => <<'EOF', loop(n) %{ register PDL_Indx this_ind = $ind(); PDL_IF_BAD( if ($ISBADVAR(this_ind,ind)) $CROAK("bad index %"IND_FLAG, n); if ($ISBAD(input())) { $SETBAD(sum(m => this_ind)); continue; },) if (this_ind<0 || this_ind>=$SIZE(m)) $CROAK("invalid index %"IND_FLAG"; range 0..%"IND_FLAG, this_ind, $SIZE(m)); $sum(m => this_ind) += $input(); %} EOF BadDoc => 'The routine barfs on bad indices, and bad inputs set target outputs bad.', Doc=>' =for ref
Broadcasting index add: add input to the ind element of sum, i.e:
sum(ind) += inputSimple example:
$x = 2;
$ind = 3;
$sum = zeroes(10);
indadd($x,$ind, $sum);
print $sum
#Result: ( 2 added to element 3 of $sum)
# [0 0 0 2 0 0 0 0 0 0]Broadcasting example:
$x = pdl( 1,2,3);
$ind = pdl( 1,4,6);
$sum = zeroes(10);
indadd($x,$ind, $sum);
print $sum."\n";
#Result: ( 1, 2, and 3 added to elements 1,4,6 $sum)
# [0 1 0 0 2 0 3 0 0 0]1D convolution along first dimension
The m-th element of the discrete convolution of an input ndarray $a of size $M, and a kernel ndarray $kern of size $P, is calculated as
n = ($P-1)/2
====
\
($a conv1d $kern)[m] = > $a_ext[m - n] * $kern[n]
/
====
n = -($P-1)/2where $a_ext is either the periodic (or reflected) extension of $a so it is equal to $a on 0..$M-1 and equal to the corresponding periodic/reflected image of $a outside that range.
$con = conv1d sequence(10), pdl(-1,0,1);
$con = conv1d sequence(10), pdl(-1,0,1), {Boundary => 'reflect'};By default, periodic boundary conditions are assumed (i.e. wrap around). Alternatively, you can request reflective boundary conditions using the Boundary option:
{Boundary => 'reflect'} # case in 'reflect' doesn't matterThe convolution is performed along the first dimension. To apply it across another dimension use the slicing routines, e.g.
$y = $x->mv(2,0)->conv1d($kernel)->mv(0,2); # along third dimThis function is useful for broadcasted filtering of 1D signals.
Compare also conv2d, convolve, fftconvolve
WARNING: conv1d processes bad values in its inputs as the numeric value of $pdl->badvalue so it is not recommended for processing pdls with bad values in them unless special care is taken. EOD Pars => 'a(m); kern(p); [o]b(m);', GenericTypes => [ppdefs_all], OtherPars => 'int reflect;', HandleBad => 0, PMCode => pp_line_numbers(__LINE__, <<'EOPM'), sub PDL::conv1d { my $opt = pop @_ if ref($_[-1]) eq 'HASH'; die 'Usage: conv1d( a(m), kern(p), [o]b(m), {Options} )' if @_<2 || @_>3; my($x,$kern) = @_; my $c = @_ == 3 ? $_[2] : PDL->null; PDL::_conv1d_int($x,$kern,$c, !(defined $opt && exists $$opt{Boundary}) ? 0 : lc $$opt{Boundary} eq "reflect"); return $c; } EOPM CHeader => ' /* Fast Modulus with proper negative behaviour */ #define REALMOD(a,b) while ((a)>=(b)) (a) -= (b); while ((a)<0) (a) += (b); ', Code => ' int reflect = $COMP(reflect); PDL_Indx m_size = $SIZE(m), p_size = $SIZE(p); PDL_Indx poff = (p_size-1)/2; loop(m) %{ complex long double tmp = 0; loop(p) %{ PDL_Indx pflip = p_size - 1 - p, i2 = m+p - poff; if (reflect && i2<0) i2 = -i2; if (reflect && i2>=m_size) i2 = m_size-(i2-m_size+1); REALMOD(i2,m_size); tmp += $a(m=>i2) * $kern(p=>pflip); %} $b() = tmp; %} ');
# this can be achieved by # ($x->dummy(0) == $y)->orover # but this one avoids a larger intermediate and potentially shortcuts pp_def('in', Pars => 'a(); b(n); [o] c()', GenericTypes => [ppdefs_all], Code => '$c() = 0; loop(n) %{ if ($a() == $b()) {$c() = 1; break;} %}', Doc => <<'EOD',
test if a is in the set of values b
$goodmsk = $labels->in($goodlabels);
print pdl(3,1,4,6,2)->in(pdl(2,3,3));
[1 0 0 0 1]in is akin to the is an element of of set theory. In principle, PDL broadcasting could be used to achieve its functionality by using a construct like
$msk = ($labels->dummy(0) == $goodlabels)->orover;However, in doesn't create a (potentially large) intermediate and is generally faster. EOD );
pp_add_exported ('', 'uniq'); pp_addpm (<< 'EOPM'); =head2 uniq
return all unique elements of an ndarray
The unique elements are returned in ascending order.
PDL> p pdl(2,2,2,4,0,-1,6,6)->uniq
[-1 0 2 4 6] # 0 is returned 2nd (sorted order)
PDL> p pdl(2,2,2,4,nan,-1,6,6)->uniq
[-1 2 4 6 nan] # NaN value is returned at endNote: The returned pdl is 1D; any structure of the input ndarray is lost. NaN values are never compare equal to any other values, even themselves. As a result, they are always unique. uniq returns the NaN values at the end of the result ndarray. This follows the Matlab usage.
See "uniqind" if you need the indices of the unique elements rather than the values.
Bad values are not considered unique by uniq and are ignored.
$x=sequence(10);
$x=$x->setbadif($x%3);
print $x->uniq;
[0 3 6 9]uniqind
Return the indices of all unique elements of an ndarray The order is in the order of the values to be consistent with uniq. NaN values never compare equal with any other value and so are always unique. This follows the Matlab usage.
PDL> p pdl(2,2,2,4,0,-1,6,6)->uniqind
[5 4 1 3 6] # the 0 at index 4 is returned 2nd, but...
PDL> p pdl(2,2,2,4,nan,-1,6,6)->uniqind
[5 1 3 6 4] # ...the NaN at index 4 is returned at endNote: The returned pdl is 1D; any structure of the input ndarray is lost.
See "uniq" if you want the unique values instead of the indices.
Bad values are not considered unique by uniqind and are ignored.
uniqvec
Return all unique vectors out of a collection
NOTE: If any vectors in the input ndarray have NaN values
they are returned at the end of the non-NaN ones. This is
because, by definition, NaN values never compare equal with
any other value.
NOTE: The current implementation does not sort the vectors
containing NaN values.The unique vectors are returned in lexicographically sorted ascending order. The 0th dimension of the input PDL is treated as a dimensional index within each vector, and the 1st and any higher dimensions are taken to run across vectors. The return value is always 2D; any structure of the input PDL (beyond using the 0th dimension for vector index) is lost.
See also "uniq" for a unique list of scalars; and qsortvec for sorting a list of vectors lexicographcally.
If a vector contains all bad values, it is ignored as in "uniq". If some of the values are good, it is treated as a normal vector. For example, [1 2 BAD] and [BAD 2 3] could be returned, but [BAD BAD BAD] could not. Vectors containing BAD values will be returned after any non-NaN and non-BAD containing vectors, followed by the NaN vectors.
Clip (threshold) an ndarray by (optional) upper or lower bounds.
$y = $x->clip(0,3);
$c = $x->clip(undef, $x);
EOD
PMCode=>pp_line_numbers(__LINE__, <<'EOPM'),
*clip = \&PDL::clip;
sub PDL::clip {
my($x, $l, $h) = @_;
my $d;
unless(defined($l) || defined($h)) {
# Deal with pathological case
if($x->is_inplace) {
$x->set_inplace(0);
return $x;
} else {
return $x->copy;
}
}
if($x->is_inplace) {
$x->set_inplace(0); $d = $x
} elsif (@_ > 3) {
$d=$_[3]
} else {
$d = PDL->nullcreate($x);
}
if(defined($l) && defined($h)) {
PDL::_clip_int($x,$l,$h,$d);
} elsif( defined($l) ) {
PDL::_lclip_int($x,$l,$d);
} elsif( defined($h) ) {
PDL::_hclip_int($x,$h,$d);
} else {
die "This can't happen (clip contingency) - file a bug";
}
return $d;
}
EOPM
); # end of clip pp_def call############################################################ # elementary statistics and histograms ############################################################
pp_def('wtstat', HandleBad => 1, Pars => 'a(n); wt(n); avg(); [o]b();', GenericTypes => [ppdefs_all], OtherPars => 'int deg', Code => <<'EOF', complex long double wtsum = 0; complex long double statsum = 0; PDL_IF_BAD(int flag = 0;,) loop(n) %{ PDL_IF_BAD(if ($ISBAD(wt()) || $ISBAD(a()) || $ISBAD(avg())) continue;flag = 1;,) PDL_Indx i; wtsum += $wt(); complex long double tmp=1; for(i=0; i<$COMP(deg); i++) tmp *= $a(); statsum += $wt() * (tmp - $avg()); %} PDL_IF_BAD(if (!flag) { $SETBAD(b()); $PDLSTATESETBAD(b); } else,) { $b() = statsum / wtsum; } EOF Doc => ' =for ref
Weighted statistical moment of given degree
This calculates a weighted statistic over the vector a. The formula is
b() = (sum_i wt_i * (a_i ** degree - avg)) / (sum_i wt_i)
',
BadDoc => '
Bad values are ignored in any calculation; C<$b> will only
have its bad flag set if the output contains any bad data.
',
);pp_def('statsover', HandleBad => 1, Pars => 'a(n); w(n); float+ [o]avg(); float+ [o]prms(); int+ [o]min(); int+ [o]max(); float+ [o]adev(); float+ [o]rms()', Code => <<'EOF', PDL_IF_GENTYPE_REAL(PDL_LDouble,PDL_CLDouble) tmp = 0, tmp1 = 0, diff = 0; $GENERIC(min) curmin = 0, curmax = 0; $GENERIC(w) norm = 0; int flag = 0; loop(n) %{ /* Accumulate sum and summed weight. */ /* perhaps should check w() for bad values too ? */ PDL_IF_BAD(if (!( $ISGOOD(a()) )) continue;,) tmp += $a()*$w(); norm += ($GENERIC(avg)) $w(); if (!flag) { curmin = $a(); curmax = $a(); flag=1; } if ($a() < curmin) { curmin = $a(); } else if ($a() > curmax) { curmax = $a(); } %} /* have at least one valid point if flag true */ PDL_IF_BAD(if ( !flag ) { $SETBAD(avg()); $PDLSTATESETBAD(avg); $SETBAD(rms()); $PDLSTATESETBAD(rms); $SETBAD(adev()); $PDLSTATESETBAD(adev); $SETBAD(min()); $PDLSTATESETBAD(min); $SETBAD(max()); $PDLSTATESETBAD(max); $SETBAD(prms()); $PDLSTATESETBAD(prms); continue; },) $avg() = tmp / norm; /* Find mean */ $min() = curmin; $max() = curmax; /* Calculate the RMS and standard deviation. */ tmp = 0; loop(n) %{ PDL_IF_BAD(if (!$ISGOOD(a())) continue;,) diff = $a()-$avg(); tmp += diff * diff * $w(); tmp1 += PDL_IF_GENTYPE_REAL(fabsl,cabsl)(diff) * $w(); %} $rms() = sqrtl( tmp/norm ); if (norm>1) $prms() = sqrtl( tmp/(norm-1) ); else PDL_IF_BAD($SETBAD(prms()),$prms() = 0); $adev() = tmp1 / norm ; EOF PMCode=>pp_line_numbers(__LINE__, <<'EOPM'), sub PDL::statsover { barf('Usage: ($mean,[$prms, $median, $min, $max, $adev, $rms]) = statsover($data,[$weights])') if @_>2; my ($data, $weights) = @_; $weights //= $data->ones(); my $median = $data->medover; my $mean = PDL->nullcreate($data); my $rms = PDL->nullcreate($data); my $min = PDL->nullcreate($data); my $max = PDL->nullcreate($data); my $adev = PDL->nullcreate($data); my $prms = PDL->nullcreate($data); PDL::_statsover_int($data, $weights, $mean, $prms, $min, $max, $adev, $rms); wantarray ? ($mean, $prms, $median, $min, $max, $adev, $rms) : $mean; } EOPM Doc => ' =for ref
Calculate useful statistics over a dimension of an ndarray
($mean,$prms,$median,$min,$max,$adev,$rms) = statsover($ndarray, $weights);This utility function calculates various useful quantities of an ndarray. These are:
the mean:
MEAN = sum (x)/ Nwith
Nbeing the number of elements in xthe population RMS deviation from the mean:
PRMS = sqrt( sum( (x-mean(x))^2 )/(N-1) )The population deviation is the best-estimate of the deviation of the population from which a sample is drawn.
the median
The median is the 50th percentile data value. Median is found by medover, so WEIGHTING IS IGNORED FOR THE MEDIAN CALCULATION.
the minimum
the maximum
the average absolute deviation:
AADEV = sum( abs(x-mean(x)) )/NRMS deviation from the mean:
RMS = sqrt(sum( (x-mean(x))^2 )/N)(also known as the root-mean-square deviation, or the square root of the variance)
This operator is a projection operator so the calculation will take place over the final dimension. Thus if the input is N-dimensional each returned value will be N-1 dimensional, to calculate the statistics for the entire ndarray either use clump(-1) directly on the ndarray or call stats. ', BadDoc =>' Bad values are simply ignored in the calculation, effectively reducing the sample size. If all data are bad then the output data are marked bad. ', );
pp_add_exported('','stats'); pp_addpm(<<'EOD'); =head2 stats
Calculates useful statistics on an ndarray
($mean,$prms,$median,$min,$max,$adev,$rms) = stats($ndarray,[$weights]);This utility calculates all the most useful quantities in one call. It works the same way as "statsover", except that the quantities are calculated considering the entire input PDL as a single sample, rather than as a collection of rows. See "statsover" for definitions of the returned quantities.
Bad values are handled; if all input values are bad, then all of the output values are flagged bad.
Calculates a histogram for given stepsize and minimum.
$h = histogram($data, $step, $min, $numbins);
$hist = zeroes $numbins; # Put histogram in existing ndarray.
histogram($data, $hist, $step, $min, $numbins);The histogram will contain $numbins bins starting from $min, each $step wide. The value in each bin is the number of values in $data that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
The output is reset in a different broadcastloop so that you can take a histogram of $a(10,12) into $b(15) and get the result you want.
For a higher-level interface, see hist.
pdl> p histogram(pdl(1,1,2),1,0,3)
[0 2 1]Calculates a histogram from weighted data for given stepsize and minimum.
$h = whistogram($data, $weights, $step, $min, $numbins);
$hist = zeroes $numbins; # Put histogram in existing ndarray.
whistogram($data, $weights, $hist, $step, $min, $numbins);The histogram will contain $numbins bins starting from $min, each $step wide. The value in each bin is the sum of the values in $weights that correspond to values in $data that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
The output is reset in a different broadcastloop so that you can take a histogram of $a(10,12) into $b(15) and get the result you want.
pdl> p whistogram(pdl(1,1,2), pdl(0.1,0.1,0.5), 1, 0, 4)
[0 0.2 0.5 0]Calculates a 2d histogram.
$h = histogram2d($datax, $datay, $stepx, $minx,
$nbinx, $stepy, $miny, $nbiny);
$hist = zeroes $nbinx, $nbiny; # Put histogram in existing ndarray.
histogram2d($datax, $datay, $hist, $stepx, $minx,
$nbinx, $stepy, $miny, $nbiny);The histogram will contain $nbinx x $nbiny bins, with the lower limits of the first one at ($minx, $miny), and with bin size ($stepx, $stepy). The value in each bin is the number of values in $datax and $datay that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
pdl> p histogram2d(pdl(1,1,1,2,2),pdl(2,1,1,1,1),1,0,3,1,0,3)
[
[0 0 0]
[0 2 2]
[0 1 0]
]Calculates a 2d histogram from weighted data.
$h = whistogram2d($datax, $datay, $weights,
$stepx, $minx, $nbinx, $stepy, $miny, $nbiny);
$hist = zeroes $nbinx, $nbiny; # Put histogram in existing ndarray.
whistogram2d($datax, $datay, $weights, $hist,
$stepx, $minx, $nbinx, $stepy, $miny, $nbiny);The histogram will contain $nbinx x $nbiny bins, with the lower limits of the first one at ($minx, $miny), and with bin size ($stepx, $stepy). The value in each bin is the sum of the values in $weights that correspond to values in $datax and $datay that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
pdl> p whistogram2d(pdl(1,1,1,2,2),pdl(2,1,1,1,1),pdl(0.1,0.2,0.3,0.4,0.5),1,0,3,1,0,3)
[
[ 0 0 0]
[ 0 0.5 0.9]
[ 0 0.1 0]
]append two ndarrays by concatenating along their first dimensions
$x = ones(2,4,7);
$y = sequence 5;
$c = $x->append($y); # size of $c is now (7,4,7) (a jumbo-ndarray ;)append appends two ndarrays along their first dimensions. The rest of the dimensions must be compatible in the broadcasting sense. The resulting size of the first dimension is the sum of the sizes of the first dimensions of the two argument ndarrays - i.e. n + m.
Similar functions include "glue" (below), which can append more than two ndarrays along an arbitrary dimension, and cat, which can append more than two ndarrays that all have the same sized dimensions. ' );
pp_addpm(<<'EOD'); =head2 glue
$c = $x->glue(<dim>,$y,...)Glue two or more PDLs together along an arbitrary dimension (N-D "append").
Sticks $x, $y, and all following arguments together along the specified dimension. All other dimensions must be compatible in the broadcasting sense.
Glue is permissive, in the sense that every PDL is treated as having an infinite number of trivial dimensions of order 1 -- so $x->glue(3,$y) works, even if $x and $y are only one dimensional.
If one of the PDLs has no elements, it is ignored. Likewise, if one of them is actually the undefined value, it is treated as if it had no elements.
If the first parameter is a defined perl scalar rather than a pdl, then it is taken as a dimension along which to glue everything else, so you can say $cube = PDL::glue(3,@image_list); if you like.
glue is implemented in pdl, using a combination of xchg and "append". It should probably be updated (one day) to a pure PP function.
Similar functions include "append" (above), which appends only two ndarrays along their first dimension, and cat, which can append more than two ndarrays that all have the same sized dimensions.
Compare two vectors lexicographically.
Returns -1 if a is less, 1 if greater, 0 if equal. ', BadDoc => ' The output is bad if any input values up to the point of inequality are bad - any after are ignored. ', );
pp_def( 'eqvec', HandleBad => 1, Pars => 'a(n); b(n); sbyte [o]c();', Code => ' PDL_IF_BAD(char anybad = 0;,) broadcastloop %{ $c() = 1; loop(n) %{ PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b())) { $SETBAD(c()); anybad = 1; break; } else,) if ($a() != $b()) { $c() = 0; PDL_IF_BAD(,break;) } %} %} PDL_IF_BAD(if (anybad) $PDLSTATESETBAD(c);,) ', Doc => 'Compare two vectors, returning 1 if equal, 0 if not equal.', BadDoc => 'The output is bad if any input values are bad.', );
pp_def('enumvec', Pars => 'v(M,N); indx [o]k(N)', Code => pp_line_numbers(__LINE__, <<'EOC'), loop (N) %{ PDL_Indx vn = N; /* preserve value of N into inner N loop */ loop (N=vn) %{ if (N == vn) { $k() = 0; continue; } /* no need to compare with self */ char matches = 1; loop (M) %{ if ($v(N=>vn) == $v()) continue; matches = 0; break; %} if (matches) { $k() = N-vn; if (N == $SIZE(N)-1) vn = N; /* last one matched, so stop */ } else { vn = N-1; break; } %} N = vn; /* skip forward */ %} EOC Doc =><<'EOD', =for ref
Enumerate a list of vectors with locally unique keys.
Given a sorted list of vectors $v, generate a vector $k containing locally unique keys for the elements of $v (where an "element" is a vector of length $M occurring in $v).
Note that the keys returned in $k are only unique over a run of a single vector in $v, so that each unique vector in $v has at least one 0 (zero) index in $k associated with it. If you need global keys, see enumvecg().
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
##------------------------------------------------------ ## enumvecg() pp_def('enumvecg', Pars => 'v(M,N); indx [o]k(N)', Code =><<'EOC', if (!$SIZE(N)) return PDL_err; PDL_Indx Nprev = 0, ki = $k(N=>0) = 0; loop(N=1) %{ loop (M) %{ if ($v(N=>Nprev) == $v()) continue; ++ki; break; %} $k() = ki; Nprev = N; %} EOC Doc =><<'EOD', =for ref
Enumerate a list of vectors with globally unique keys.
Given a sorted list of vectors $v, generate a vector $k containing globally unique keys for the elements of $v (where an "element" is a vector of length $M occurring in $v). Basically does the same thing as:
$k = $v->vsearchvec($v->uniqvec);... but somewhat more efficiently.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('vsearchvec', Pars => 'find(M); which(M,N); indx [o]found();', Code => q( int carp=0; broadcastloop %{ PDL_Indx n1=$SIZE(N)-1, nlo=-1, nhi=n1, nn; int cmpval, is_asc_sorted; // //-- get sort direction $CMPVEC($which(N=>n1),$which(N=>0),M,cmpval); is_asc_sorted = (cmpval > 0); // //-- binary search while (nhi-nlo > 1) { nn = (nhi+nlo) >> 1; $CMPVEC($find(),$which(N=>nn),M,cmpval); if ((cmpval > 0) == is_asc_sorted) nlo=nn; else nhi=nn; } if (nlo==-1) { nhi=0; } else if (nlo==n1) { $CMPVEC($find(),$which(N=>n1),M,cmpval); if (cmpval != 0) carp = 1; nhi = n1; } else { nhi = nlo+1; } $found() = nhi; %} if (carp) warn("some values had to be extrapolated"); ), Doc=><<'EOD' =for ref
Routine for searching N-dimensional values - akin to vsearch() for vectors.
$found = vsearchvec($find, $which);
$nearest = $which->dice_axis(1,$found);Returns for each row-vector in $find the index along dimension N of the least row vector of $which greater or equal to it. $which should be sorted in increasing order. If the value of $find is larger than any member of $which, the index to the last element of $which is returned.
See also: "vsearch". Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('unionvec', Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC($SIZE(NA) + $SIZE(NB))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::unionvec { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($nc)); $nc = PDL->null if (!defined($nc)); PDL::_unionvec_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); return $c->slice(",0:".($nc->max-1)); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=$SIZE(NC), sizeNA=$SIZE(NA), sizeNB=$SIZE(NB); int cmpval; loop (NC) %{ if (nai < sizeNA && nbi < sizeNB) { $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval); } else if (nai < sizeNA) { cmpval = -1; } else if (nbi < sizeNB) { cmpval = 1; } else { nci=NC; break; } // if (cmpval < 0) { //-- CASE: a < b loop (M) %{ $c() = $a(NA=>nai); %} nai++; } else if (cmpval > 0) { //-- CASE: a > b loop (M) %{ $c() = $b(NB=>nbi); %} nbi++; } else { //-- CASE: a == b loop (M) %{ $c() = $a(NA=>nai); %} nai++; nbi++; } %} $nc() = nci; //-- zero unpopulated outputs loop(NC=nci,M) %{ $c() = 0; %} ), Doc=><<'EOD' =for ref
Union of two vector-valued PDLs.
Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the union.
In scalar context, slices $c() to the actual number of elements in the union and returns the sliced PDL.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('intersectvec', Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC(PDLMIN($SIZE(NA),$SIZE(NB)))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::intersectvec { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($c)); $nc = PDL->null if (!defined($nc)); PDL::_intersectvec_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); my $nc_max = $nc->max; return ($nc_max > 0 ? $c->slice(",0:".($nc_max-1)) : $c->reshape($c->dim(0), 0, ($c->dims)[2..($c->ndims-1)])); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC); int cmpval; for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB; ) { $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval); // if (cmpval < 0) { //-- CASE: a < b nai++; } else if (cmpval > 0) { //-- CASE: a > b nbi++; } else { //-- CASE: a == b loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %} nai++; nbi++; nci++; } } $nc() = nci; //-- zero unpopulated outputs loop(NC=nci,M) %{ $c() = 0; %} ), Doc=><<'EOD' =for ref
Intersection of two vector-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the intersection.
In scalar context, slices $c() to the actual number of elements in the intersection and returns the sliced PDL.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('setdiffvec', Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC($SIZE(NA))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::setdiffvec { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($c)); $nc = PDL->null if (!defined($nc)); PDL::_setdiffvec_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); my $nc_max = $nc->max; return ($nc_max > 0 ? $c->slice(",0:".($nc_max-1)) : $c->reshape($c->dim(0), 0, ($c->dims)[2..($c->ndims-1)])); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC); int cmpval; for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB ; ) { $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval); // if (cmpval < 0) { //-- CASE: a < b loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %} nai++; nci++; } else if (cmpval > 0) { //-- CASE: a > b nbi++; } else { //-- CASE: a == b nai++; nbi++; } } for ( ; nci < sizeNC && nai < sizeNA ; nai++,nci++ ) { loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %} } $nc() = nci; //-- zero unpopulated outputs loop (NC=nci,M) %{ $c() = 0; %} ), Doc=><<'EOD' =for ref
Set-difference ($a() \ $b()) of two vector-valued PDLs.
Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the computed vector set.
In scalar context, slices $c() to the actual number of elements in the output vector set and returns the sliced PDL.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_add_macros( CMPVAL => sub { my ($val1, $val2) = @_; "(($val1) < ($val2) ? -1 : ($val1) > ($val2) ? 1 : 0)"; }, );
pp_def('union_sorted', Pars => 'a(NA); b(NB); [o]c(NC=CALC($SIZE(NA) + $SIZE(NB))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::union_sorted { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($c)); $nc = PDL->null if (!defined($nc)); PDL::_union_sorted_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); return $c->slice("0:".($nc->max-1)); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=$SIZE(NC), sizeNA=$SIZE(NA), sizeNB=$SIZE(NB); int cmpval; loop (NC) %{ if (nai < sizeNA && nbi < sizeNB) { cmpval = $CMPVAL($a(NA=>nai), $b(NB=>nbi)); } else if (nai < sizeNA) { cmpval = -1; } else if (nbi < sizeNB) { cmpval = 1; } else { nci = NC; break; } // if (cmpval < 0) { //-- CASE: a < b $c() = $a(NA=>nai); nai++; } else if (cmpval > 0) { //-- CASE: a > b $c() = $b(NB=>nbi); nbi++; } else { //-- CASE: a == b $c() = $a(NA=>nai); nai++; nbi++; } %} $nc() = nci; loop (NC=nci) %{ //-- zero unpopulated outputs $c() = 0; %} ), Doc=><<'EOD' =for ref
Union of two flat sorted unique-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order and contain no duplicates. On return, $nc() holds the actual number of values in the union.
In scalar context, reshapes $c() to the actual number of elements in the union and returns it.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('intersect_sorted', Pars => 'a(NA); b(NB); [o]c(NC=CALC(PDLMIN($SIZE(NA),$SIZE(NB)))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::intersect_sorted { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($c)); $nc = PDL->null if (!defined($nc)); PDL::_intersect_sorted_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); my $nc_max = $nc->max; return ($nc_max > 0 ? $c->slice("0:".($nc_max-1)) : $c->reshape(0, ($c->dims)[1..($c->ndims-1)])); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC); int cmpval; for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB; ) { cmpval = $CMPVAL($a(NA=>nai),$b(NB=>nbi)); // if (cmpval < 0) { //-- CASE: a < b nai++; } else if (cmpval > 0) { //-- CASE: a > b nbi++; } else { //-- CASE: a == b $c(NC=>nci) = $a(NA=>nai); nai++; nbi++; nci++; } } $nc() = nci; for ( ; nci < sizeNC; nci++) { //-- zero unpopulated outputs $c(NC=>nci) = 0; } ), Doc=><<'EOD' =for ref
Intersection of two flat sorted unique-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order and contain no duplicates. On return, $nc() holds the actual number of values in the intersection.
In scalar context, reshapes $c() to the actual number of elements in the intersection and returns it.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('setdiff_sorted', Pars => 'a(NA); b(NB); [o]c(NC=CALC($SIZE(NA))); indx [o]nc()', PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub PDL::setdiff_sorted { my ($a,$b,$c,$nc) = @_; $c = PDL->null if (!defined($c)); $nc = PDL->null if (!defined($nc)); PDL::_setdiff_sorted_int($a,$b,$c,$nc); return ($c,$nc) if (wantarray); my $nc_max = $nc->max; return ($nc_max > 0 ? $c->slice("0:".($nc_max-1)) : $c->reshape(0, ($c->dims)[1..($c->ndims-1)])); } EOD Code => q( PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC); int cmpval; for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB ; ) { cmpval = $CMPVAL($a(NA=>nai),$b(NB=>nbi)); // if (cmpval < 0) { //-- CASE: a < b $c(NC=>nci) = $a(NA=>nai); nai++; nci++; } else if (cmpval > 0) { //-- CASE: a > b nbi++; } else { //-- CASE: a == b nai++; nbi++; } } for ( ; nci < sizeNC && nai < sizeNA ; nai++,nci++ ) { $c(NC=>nci) = $a(NA=>nai); } $nc() = nci; for ( ; nci < sizeNC; nci++) { //-- zero unpopulated outputs $c(NC=>nci) = 0; } ), Doc=><<'EOD' =for ref
Set-difference ($a() \ $b()) of two flat sorted unique-valued PDLs.
Input PDLs $a() and $b() MUST be sorted in lexicographic order and contain no duplicate values. On return, $nc() holds the actual number of values in the computed vector set.
In scalar context, reshapes $c() to the actual number of elements in the difference set and returns it.
Contributed by Bryan Jurish <moocow@cpan.org>. EOD );
pp_def('vcos', Pars => join('', "a(M,N);", ##-- logical (D,T) "b(M);", ##-- logical (D,1) "float+ [o]vcos(N);", ##-- logical (T) ), GenericTypes => [ppdefs_all], HandleBad => 1, Code => pp_line_numbers(__LINE__, <<'EOF'), broadcastloop %{ $GENERIC(vcos) bnorm = 0; loop(M) %{ PDL_IF_BAD(if ($ISBAD(b())) continue;,) bnorm += $b() * $b(); %} if (bnorm == 0) { /*-- null-vector b(): set all vcos()=NAN --*/ loop (N) %{ $vcos() = NAN; %} continue; } bnorm = sqrtl(bnorm); /*-- usual case: compute values for N-slice of b() --*/ loop (N) %{ $GENERIC(vcos) anorm = 0, vval = 0; loop (M) %{ PDL_IF_BAD(if ($ISBAD(a())) continue;,) $GENERIC(vcos) aval = $a(); anorm += aval * aval; PDL_IF_BAD(if ($ISBAD(b())) continue;,) vval += aval * $b(); %} /*-- normalize --*/ anorm = sqrtl(anorm); if (anorm != 0) { /*-- usual case a(), b() non-null --*/ $vcos() = vval / (anorm * bnorm); } else { /*-- null-vector a(): set vcos()=NAN --*/ $vcos() = NAN; } %} %} if ( $PDLSTATEISBAD(a) || $PDLSTATEISBAD(b) ) $PDLSTATESETBAD(vcos); EOF Doc => q{ Computes the vector cosine similarity of a dense vector $b() with respect to each row $a(*,i) of a dense PDL $a(). This is basically the same thing as:
inner($a, $b) / $a->magnover * $b->magnover... but should be much faster to compute, and avoids allocating potentially large temporaries for the vector magnitudes. Output values in $vcos() are cosine similarities in the range [-1,1], except for zero-magnitude vectors which will result in NaN values in $vcos().
You can use PDL broadcasting to batch-compute distances for multiple $b() vectors simultaneously:
$bx = random($M, $NB); ##-- get $NB random vectors of size $N
$vcos = vcos($a,$bx); ##-- $vcos(i,j) ~ sim($a(,i),$b(,j))Contributed by Bryan Jurish <moocow@cpan.org>. }, BadDoc=> q{ vcos() will set the bad status flag on the output $vcos() if it is set on either of the inputs $a() or $b(), but BAD values will otherwise be ignored for computing the cosine similarity. }, );
pp_addhdr(<<'EOH'); extern int pdl_srand_threads; extern uint64_t *pdl_rand_state; void pdl_srand(uint64_t **s, uint64_t seed, int n); double pdl_drand(uint64_t *s); #define PDL_MAYBE_SRAND \ if (pdl_srand_threads < 0) \ pdl_srand(&pdl_rand_state, PDL->pdl_seed(), PDL->online_cpus()); #define PDL_RAND_SET_OFFSET(v, thr, pdl) \ if (v < 0) { \ if (thr.mag_nthr >= 0) { \ int thr_no = PDL->magic_get_thread(pdl); \ if (thr_no < 0) return PDL->make_error_simple(PDL_EFATAL, "Invalid pdl_magic_get_thread!"); \ v = thr_no == 0 ? thr_no : thr_no % PDL->online_cpus(); \ } else { \ v = 0; \ } \ } EOH
pp_def( 'srandom', Pars=>'a();', GenericTypes => ['Q'], Code => <<'EOF', pdl_srand(&pdl_rand_state, (uint64_t)$a(), PDL->online_cpus()); EOF NoPthread => 1, HaveBroadcasting => 0, Doc=> <<'EOF', =for ref
Seed random-number generator with a 64-bit int. Will generate seed data for a number of threads equal to the return-value of "online_cpus" in PDL::Core. As of 2.062, the generator changed from Perl's generator to xoshiro256++ (see https://prng.di.unimi.it/). Before PDL 2.090, this was called srand, but was renamed to avoid clashing with Perl's built-in.
srandom(); # uses current time
srandom(5); # fixed number e.g. for testingEOF PMCode=>pp_line_numbers(__LINE__, <<'EOD'), *srandom = \&PDL::srandom; sub PDL::srandom { PDL::_srandom_int($_[0] // PDL::Core::seed()) } EOD );
pp_def( 'random', Pars=>'[o] a();', PMFunc => '', Code => <<'EOF', PDL_MAYBE_SRAND int rand_offset = -1; broadcastloop %{ PDL_RAND_SET_OFFSET(rand_offset, $PRIV(broadcast), $PDL(a)); $a() = pdl_drand(pdl_rand_state + 4*rand_offset); %} EOF Doc=> <<'EOF', =for ref
Constructor which returns ndarray of random numbers, real data-types only.
$x = random([type], $nx, $ny, $nz,...);
$x = random $y;etc (see zeroes).
This is the uniform distribution between 0 and 1 (assumedly excluding 1 itself). The arguments are the same as zeroes (q.v.) - i.e. one can specify dimensions, types or give a template.
You can use the PDL function "srandom" to seed the random generator. If it has not been called yet, it will be with the current time. As of 2.062, the generator changed from Perl's generator to xoshiro256++ (see https://prng.di.unimi.it/). EOF PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub random { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->random : PDL->random(@_) } sub PDL::random { splice @_, 1, 0, double() if !ref($_[0]) and @_<=1; my $x = &PDL::Core::_construct; PDL::_random_int($x); return $x; } EOD );
pp_def( 'randsym', Pars=>'[o] a();', PMFunc => '', Code => <<'EOF', PDL_MAYBE_SRAND int rand_offset = -1; broadcastloop %{ PDL_RAND_SET_OFFSET(rand_offset, $PRIV(broadcast), $PDL(a)); long double tmp; do tmp = pdl_drand(pdl_rand_state + 4*rand_offset); while (tmp == 0.0); /* 0 < tmp < 1 */ $a() = tmp; %} EOF Doc=> <<'EOF', =for ref
Constructor which returns ndarray of random numbers, real data-types only.
$x = randsym([type], $nx, $ny, $nz,...);
$x = randsym $y;etc (see zeroes).
This is the uniform distribution between 0 and 1 (excluding both 0 and 1, cf "random"). The arguments are the same as zeroes (q.v.) - i.e. one can specify dimensions, types or give a template.
You can use the PDL function "srandom" to seed the random generator. If it has not been called yet, it will be with the current time. EOF PMCode=>pp_line_numbers(__LINE__, <<'EOD'), sub randsym { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->randsym : PDL->randsym(@_) } sub PDL::randsym { splice @_, 1, 0, double() if !ref($_[0]) and @_<=1; my $x = &PDL::Core::_construct; PDL::_randsym_int($x); return $x; } EOD );
pp_add_exported('','grandom'); pp_addpm(<<'EOD'); =head2 grandom
Constructor which returns ndarray of Gaussian random numbers
$x = grandom([type], $nx, $ny, $nz,...);
$x = grandom $y;etc (see zeroes).
This is generated using the math library routine ndtri.
Mean = 0, Stddev = 1
You can use the PDL function "srandom" to seed the random generator. If it has not been called yet, it will be with the current time.
vsearch
Signature: ( vals(); xs(n); [o] indx(); [\%options] )Efficiently search for values in a sorted ndarray, returning indices.
$idx = vsearch( $vals, $x, [\%options] );
vsearch( $vals, $x, $idx, [\%options ] );vsearch performs a binary search in the ordered ndarray $x, for the values from $vals ndarray, returning indices into $x. What is a "match", and the meaning of the returned indices, are determined by the options.
The mode option indicates which method of searching to use, and may be one of:
sample-
invoke vsearch_sample, returning indices appropriate for sampling within a distribution.
insert_leftmost-
invoke vsearch_insert_leftmost, returning the left-most possible insertion point which still leaves the ndarray sorted.
insert_rightmost-
invoke vsearch_insert_rightmost, returning the right-most possible insertion point which still leaves the ndarray sorted.
match-
invoke vsearch_match, returning the index of a matching element, else -(insertion point + 1)
bin_inclusive-
invoke vsearch_bin_inclusive, returning an index appropriate for binning on a grid where the left bin edges are inclusive of the bin. See below for further explanation of the bin.
bin_exclusive-
invoke vsearch_bin_exclusive, returning an index appropriate for binning on a grid where the left bin edges are exclusive of the bin. See below for further explanation of the bin.
The default value of mode is sample.
use PDL;
my @modes = qw( sample insert_leftmost insert_rightmost match
bin_inclusive bin_exclusive );
# Generate a sequence of 3 zeros, 3 ones, ..., 3 fours.
my $x = zeroes(3,5)->yvals->flat;
for my $mode ( @modes ) {
# if the value is in $x
my $contained = 2;
my $idx_contained = vsearch( $contained, $x, { mode => $mode } );
my $x_contained = $x->copy;
$x_contained->slice( $idx_contained ) .= 9;
# if the value is not in $x
my $not_contained = 1.5;
my $idx_not_contained = vsearch( $not_contained, $x, { mode => $mode } );
my $x_not_contained = $x->copy;
$x_not_contained->slice( $idx_not_contained ) .= 9;
print sprintf("%-23s%30s\n", '$x', $x);
print sprintf("%-23s%30s\n", "$mode ($contained)", $x_contained);
print sprintf("%-23s%30s\n\n", "$mode ($not_contained)", $x_not_contained);
}
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# sample (2) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
# sample (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
#
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# insert_leftmost (2) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
# insert_leftmost (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
#
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# insert_rightmost (2) [0 0 0 1 1 1 2 2 2 9 3 3 4 4 4]
# insert_rightmost (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
#
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# match (2) [0 0 0 1 1 1 2 9 2 3 3 3 4 4 4]
# match (1.5) [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
#
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# bin_inclusive (2) [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
# bin_inclusive (1.5) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
#
# $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
# bin_exclusive (2) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
# bin_exclusive (1.5) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]Also see vsearch_sample, vsearch_insert_leftmost, vsearch_insert_rightmost, vsearch_match, vsearch_bin_inclusive, and vsearch_bin_exclusive
routine for 1D linear interpolation
Given a set of points ($x,$y), use linear interpolation to find the values $yi at a set of points $xi.
interpolate uses a binary search to find the suspects, er..., interpolation indices and therefore abscissas (ie $x) have to be strictly ordered (increasing or decreasing). For interpolation at lots of closely spaced abscissas an approach that uses the last index found as a start for the next search can be faster (compare Numerical Recipes hunt routine). Feel free to implement that on top of the binary search if you like. For out of bounds values it just does a linear extrapolation and sets the corresponding element of $err to 1, which is otherwise 0.
See also "interpol", which uses the same routine, differing only in the handling of extrapolation - an error message is printed rather than returning an error ndarray.
Note that interpolate can use complex values for $y and $yi but $x and $xi must be real. EOD );
pp_add_exported('', 'interpol'); pp_addpm(<<'EOD'); =head2 interpol
Signature: (xi(); x(n); y(n); [o] yi())routine for 1D linear interpolation
$yi = interpol($xi, $x, $y)interpol uses the same search method as "interpolate", hence $x must be strictly ordered (either increasing or decreasing). The difference occurs in the handling of out-of-bounds values; here an error message is printed.
interpND
Interpolate values from an N-D ndarray, with switchable method
$source = 10*xvals(10,10) + yvals(10,10);
$index = pdl([[2.2,3.5],[4.1,5.0]],[[6.0,7.4],[8,9]]);
print $source->interpND( $index );InterpND acts like indexND, collapsing $index by lookup into $source; but it does interpolation rather than direct sampling. The interpolation method and boundary condition are switchable via an options hash.
By default, linear or sample interpolation is used, with constant value outside the boundaries of the source pdl. No dataflow occurs, because in general the output is computed rather than indexed.
All the interpolation methods treat the pixels as value-centered, so the sample method will return $a->(0) for coordinate values on the set [-0.5,0.5], and all methods will return $a->(1) for a coordinate value of exactly 1.
Recognized options:
- method
-
Values can be:
0, s, sample, Sample (default for integer source types)
The nearest value is taken. Pixels are regarded as centered on their respective integer coordinates (no offset from the linear case).
1, l, linear, Linear (default for floating point source types)
The values are N-linearly interpolated from an N-dimensional cube of size 2.
3, c, cube, cubic, Cubic
The values are interpolated using a local cubic fit to the data. The fit is constrained to match the original data and its derivative at the data points. The second derivative of the fit is not continuous at the data points. Multidimensional datasets are interpolated by the successive-collapse method.
(Note that the constraint on the first derivative causes a small amount of ringing around sudden features such as step functions).
f, fft, fourier, Fourier
The source is Fourier transformed, and the interpolated values are explicitly calculated from the coefficients. The boundary condition option is ignored -- periodic boundaries are imposed.
If you pass in the option "fft", and it is a list (ARRAY) ref, then it is a stash for the magnitude and phase of the source FFT. If the list has two elements then they are taken as already computed; otherwise they are calculated and put in the stash.
- b, bound, boundary, Boundary
-
This option is passed unmodified into indexND, which is used as the indexing engine for the interpolation. Some current allowed values are 'extend', 'periodic', 'truncate', and 'mirror' (default is 'truncate').
- bad
-
contains the fill value used for 'truncate' boundary. (default 0)
- fft
-
An array ref whose associated list is used to stash the FFT of the source data, for the FFT method.
one2nd
Converts a one dimensional index ndarray to a set of ND coordinates
@coords=one2nd($x, $indices)returns an array of ndarrays containing the ND indexes corresponding to the one dimensional list indices. The indices are assumed to correspond to array $x clumped using clump(-1). This routine is used in the old vector form of "whichND", but is useful on its own occasionally.
Returned ndarrays have the indx datatype. $indices can have values larger than $x->nelem but negative values in $indices will not give the answer you expect.
pdl> $x=pdl [[[1,2],[-1,1]], [[0,-3],[3,2]]]; $c=$x->clump(-1)
pdl> $maxind=maximum_ind($c); p $maxind;
6
pdl> print one2nd($x, maximum_ind($c))
0 1 1
pdl> p $x->at(0,1,1)
3Returns indices of non-zero values from a 1-D PDL
$i = which($mask);returns a pdl with indices for all those elements that are nonzero in the mask. Note that the returned indices will be 1D. If you feed in a multidimensional mask, it will be flattened before the indices are calculated. See also "whichND" for multidimensional masks.
If you want to index into the original mask or a similar ndarray with output from which, remember to flatten it before calling index:
$data = random 5, 5;
$idx = which $data > 0.5; # $idx is now 1D
$bigsum = $data->flat->index($idx)->sum; # flatten before indexingCompare also "where" for similar functionality.
SEE ALSO:
"which_both" returns separately the indices of both nonzero and zero values in the mask.
"where_both" returns separately slices of both nonzero and zero values in the mask.
"where" returns associated values from a data PDL, rather than indices into the mask PDL.
"whichND" returns N-D indices into a multidimensional PDL.
pdl> $x = sequence(10); p $x
[0 1 2 3 4 5 6 7 8 9]
pdl> $indx = which($x>6); p $indx
[7 8 9]Returns indices of nonzero and zero values in a mask PDL
($i, $c_i) = which_both($mask);This works just as "which", but the complement of $i will be in $c_i.
pdl> p $x = sequence(10)
[0 1 2 3 4 5 6 7 8 9]
pdl> ($big, $small) = which_both($x >= 5); p "$big\n$small"
[5 6 7 8 9]
[0 1 2 3 4]See also "whichND_both" for the n-dimensional version.
Collects the coordinates of non-zero, non-bad values in each 1D mask in ndarray at the start of the output, and fills the rest with -1.
By using "xchg" in PDL::Slices etc. it is possible to use any dimension.
my $a = pdl q[3 4 2 3 2 3 1];
my $b = $a->uniq;
my $c = +($a->dummy(0) == $b)->transpose;
print $c, $c->whichover;
# [
# [0 0 0 0 0 0 1]
# [0 0 1 0 1 0 0]
# [1 0 0 1 0 1 0]
# [0 1 0 0 0 0 0]
# ]
# [
# [ 6 -1 -1 -1 -1 -1 -1]
# [ 2 4 -1 -1 -1 -1 -1]
# [ 0 3 5 -1 -1 -1 -1]
# [ 1 -1 -1 -1 -1 -1 -1]
# ]EOF );
pp_def('approx_artol', Pars => 'got(); expected(); sbyte [o] result()', OtherPars => 'double atol; double rtol', OtherParsDefaults => { atol => 1e-6, rtol => 0 }, GenericTypes => [ppdefs_all], ArgOrder => 1, HandleBad => 1, Code => pp_line_numbers(__LINE__, <<'EOF'), double atol2 = $COMP(atol)*$COMP(atol), rtol2 = $COMP(rtol)*$COMP(rtol); PDL_IF_BAD(char got_badflag = !!$PDLSTATEISBAD(got); char exp_badflag = !!$PDLSTATEISBAD(expected);,) broadcastloop %{ $GENERIC() expctd = $expected(); if (PDL_ISNAN_$PPSYM()($got()) && PDL_ISNAN_$PPSYM()(expctd)) { $result() = 1; continue; } if (PDL_ISNAN_$PPSYM()($got()) || PDL_ISNAN_$PPSYM()(expctd)) { $result() = 0; continue; } PDL_IF_BAD( if ((got_badflag && $ISBAD(got())) && (exp_badflag && $ISBADVAR(expctd,expected))) { $result() = 1; continue; } if ((got_badflag && $ISBAD(got())) || (exp_badflag && $ISBADVAR(expctd,expected))) { $result() = 0; continue; } ,) if ($got() == expctd) { $result() = 1; continue; } $GENERIC() diff = $got() - expctd; double abs_diff2 = PDL_IF_GENTYPE_REAL( diff * diff, (creall(diff) * creall(diff)) + (cimagl(diff) * cimagl(diff)) ); if (abs_diff2 <= atol2) { $result() = 1; continue; } double rel_diff2 = rtol2 * PDL_IF_GENTYPE_REAL( expctd * expctd, ((creall(expctd) * creall(expctd)) + (cimagl(expctd) * cimagl(expctd))) ); if (abs_diff2 <= rel_diff2) { $result() = 1; continue; } $result() = 0; %} EOF Doc => <<'EOF', =for ref
Returns sbyte mask whether abs($got()-$expected())> <= either absolute or relative (rtol * $expected()) tolerances.
Relative tolerance defaults to zero, and absolute tolerance defaults to 1e-6, for compatibility with "approx" in PDL::Core.
Works with complex numbers, and to avoid expensive sqrting uses the squares of the input quantities and differences. Bear this in mind for numbers outside the range (for double) of about 1e-154..1e154.
Handles NaNs by showing them approximately equal (i.e. true in the output) if both values are NaN, and not otherwise.
Adapted from code by Edward Baudrez, test changed from < to <=. EOF BadDoc => <<'EOF', Handles bad values similarly to NaNs, above. This includes if only one of the two input ndarrays has their badflag true. EOF );
pp_add_exported("", 'where'); pp_addpm(<<'EOD'); =head2 where
Use a mask to select values from one or more data PDLs
where accepts one or more data ndarrays and a mask ndarray. It returns a list of output ndarrays, corresponding to the input data ndarrays. Each output ndarray is a 1-dimensional list of values in its corresponding data ndarray. The values are drawn from locations where the mask is nonzero.
The output PDLs are still connected to the original data PDLs, for the purpose of dataflow.
where combines the functionality of "which" and index into a single operation.
BUGS:
While where works OK for most N-dimensional cases, it does not broadcast properly over (for example) the (N+1)th dimension in data that is compared to an N-dimensional mask. Use whereND for that.
$i = $x->where($x+5 > 0); # $i contains those elements of $x
# where mask ($x+5 > 0) is 1
$i .= -5; # Set those elements (of $x) to -5. Together, these
# commands clamp $x to a maximum of -5.It is also possible to use the same mask for several ndarrays with the same call:
($i,$j,$k) = where($x,$y,$z, $x+5>0);Note: $i is always 1-D, even if $x is >1-D.
WARNING: The first argument (the values) and the second argument (the mask) currently have to have the exact same dimensions (or horrible things happen). You *cannot* broadcast over a smaller mask, for example.
where_both
Returns slices (non-zero in mask, zero) of an ndarray according to a mask
($match_vals, $non_match_vals) = where_both($pdl, $mask);This works like "which_both", but (flattened) data-flowing slices rather than index-sets are returned.
pdl> p $x = sequence(10) + 2
[2 3 4 5 6 7 8 9 10 11]
pdl> ($big, $small) = where_both($x, $x > 5); p "$big\n$small"
[6 7 8 9 10 11]
[2 3 4 5]
pdl> p $big += 2, $small -= 1
[8 9 10 11 12 13] [1 2 3 4]
pdl> p $x
[1 2 3 4 8 9 10 11 12 13]whereND
where with support for ND masks and broadcasting
whereND accepts one or more data ndarrays and a mask ndarray. It returns a list of output ndarrays, corresponding to the input data ndarrays. The values are drawn from locations where the mask is nonzero.
whereND differs from where in that the mask dimensionality is preserved which allows for proper broadcasting of the selection operation over higher dimensions.
As with where the output PDLs are still connected to the original data PDLs, for the purpose of dataflow.
$sdata = whereND $data, $mask
($s1, $s2, ..., $sn) = whereND $d1, $d2, ..., $dn, $maskwhere
$data is M dimensional
$mask is N < M dimensional
dims($data) 1..N == dims($mask) 1..N
with broadcasting over N+1 to M dimensions$data = sequence(4,3,2); # example data array
$mask4 = (random(4)>0.5); # example 1-D mask array, has $n4 true values
$mask43 = (random(4,3)>0.5); # example 2-D mask array, has $n43 true values
$sdat4 = whereND $data, $mask4; # $sdat4 is a [$n4,3,2] pdl
$sdat43 = whereND $data, $mask43; # $sdat43 is a [$n43,2] pdlJust as with where, you can use the returned value in an assignment. That means that both of these examples are valid:
# Used to create a new slice stored in $sdat4:
$sdat4 = $data->whereND($mask4);
$sdat4 .= 0;
# Used in lvalue context:
$data->whereND($mask4) .= 0;SEE ALSO:
"whichND" returns N-D indices into a multidimensional PDL, from a mask.
whereND_both
where_both with support for ND masks and broadcasting
This works like "whichND_both", but data-flowing slices rather than index-sets are returned.
whereND_both differs from where_both in that the mask dimensionality is preserved which allows for proper broadcasting of the selection operation over higher dimensions.
As with where_both the output PDLs are still connected to the original data PDLs, for the purpose of dataflow.
($match_vals, $non_match_vals) = whereND_both($pdl, $mask);whichND
Return the coordinates of non-zero values in a mask.
WhichND returns the N-dimensional coordinates of each nonzero value in a mask PDL with any number of dimensions. The returned values arrive as an array-of-vectors suitable for use in indexND or range.
$coords = whichND($mask);returns a PDL containing the coordinates of the elements that are non-zero in $mask, suitable for use in "indexND" in PDL::Slices. The 0th dimension contains the full coordinate listing of each point; the 1st dimension lists all the points. For example, if $mask has rank 4 and 100 matching elements, then $coords has dimension 4x100.
If no such elements exist, then whichND returns a structured empty PDL: an Nx0 PDL that contains no values (but matches, broadcasting-wise, with the vectors that would be produced if such elements existed).
DEPRECATED BEHAVIOR IN LIST CONTEXT:
whichND once delivered different values in list context than in scalar context, for historical reasons. In list context, it returned the coordinates transposed, as a collection of 1-PDLs (one per dimension) in a list. This usage is deprecated in PDL 2.4.10, and will cause a warning to be issued every time it is encountered. To avoid the warning, you can set the global variable "$PDL::whichND" to 's' to get scalar behavior in all contexts, or to 'l' to get list behavior in list context.
In later versions of PDL, the deprecated behavior will disappear. Deprecated list context whichND expressions can be replaced with:
@list = $x->whichND->mv(0,-1)->dog;SEE ALSO:
"which" finds coordinates of nonzero values in a 1-D mask.
"where" extracts values from a data PDL that are associated with nonzero values in a mask PDL.
"indexND" in PDL::Slices can be fed the coordinates to return the values.
pdl> $s=sequence(10,10,3,4)
pdl> ($x, $y, $z, $w)=whichND($s == 203); p $x, $y, $z, $w
[3] [0] [2] [0]
pdl> print $s->at(list(cat($x,$y,$z,$w)))
203whichND_both
Return the coordinates of non-zero values in a mask.
Like "which_both", but returns the N-dimensional coordinates (like "whichND") of the nonzero, zero values in the mask PDL. The returned values arrive as an array-of-vectors suitable for use in indexND or range. Added in 2.099.
($nonzero_coords, $zero_coords) = whichND_both($mask);SEE ALSO:
"which" finds coordinates of nonzero values in a 1-D mask.
"where" extracts values from a data PDL that are associated with nonzero values in a mask PDL.
"indexND" in PDL::Slices can be fed the coordinates to return the values.
pdl> $s=sequence(10,10,3,4)
pdl> ($x, $y, $z, $w)=whichND($s == 203); p $x, $y, $z, $w
[3] [0] [2] [0]
pdl> print $s->at(list(cat($x,$y,$z,$w)))
203setops
Implements simple set operations like union and intersection
Usage: $set = setops($x, <OPERATOR>, $y);The operator can be OR, XOR or AND. This is then applied to $x viewed as a set and $y viewed as a set. Set theory says that a set may not have two or more identical elements, but setops takes care of this for you, so $x=pdl(1,1,2) is OK. The functioning is as follows:
OR-
The resulting vector will contain the elements that are either in
$xor in$yor both. This is the union in set operation terms XOR-
The resulting vector will contain the elements that are either in
$xor$y, but not in both. This isUnion($x, $y) - Intersection($x, $y)in set operation terms.
AND-
The resulting vector will contain the intersection of
$xand$y, so the elements that are in both$xand$y. Note that for convenience this operation is also aliased to "intersect".
It should be emphasized that these routines are used when one or both of the sets $x, $y are hard to calculate or that you get from a separate subroutine.
Finally IDL users might be familiar with Craig Markwardt's cmset_op.pro routine which has inspired this routine although it was written independently However the present routine has a few less options (but see the examples)
You will very often use these functions on an index vector, so that is what we will show here. We will in fact something slightly silly. First we will find all squares that are also cubes below 10000.
Create a sequence vector:
pdl> $x = sequence(10000)Find all odd and even elements:
pdl> ($even, $odd) = which_both( ($x % 2) == 0)Find all squares
pdl> $squares= which(ceil(sqrt($x)) == floor(sqrt($x)))Find all cubes (being careful with roundoff error!)
pdl> $cubes= which(ceil($x**(1.0/3.0)) == floor($x**(1.0/3.0)+1e-6))Then find all squares that are cubes:
pdl> $both = setops($squares, 'AND', $cubes)And print these (assumes that PDL::NiceSlice is loaded!)
pdl> p $x($both)
[0 1 64 729 4096]Then find all numbers that are either cubes or squares, but not both:
pdl> $cube_xor_square = setops($squares, 'XOR', $cubes)
pdl> p $cube_xor_square->nelem()
112So there are a total of 112 of these!
Finally find all odd squares:
pdl> $odd_squares = setops($squares, 'AND', $odd)Another common occurrence is to want to get all objects that are in $x and in the complement of $y. But it is almost always best to create the complement explicitly since the universe that both are taken from is not known. Thus use "which_both" if possible to keep track of complements.
If this is impossible the best approach is to make a temporary:
This creates an index vector the size of the universe of the sets and set all elements in $y to 0
pdl> $tmp = ones($n_universe); $tmp($y) .= 0;This then finds the complement of $y
pdl> $C_b = which($tmp == 1);and this does the final selection:
pdl> $set = setops($x, 'AND', $C_b)intersect
Calculate the intersection of two ndarrays
Usage: $set = intersect($x, $y);This routine is merely a simple interface to "setops". See that for more information
Find all numbers less that 100 that are of the form 2*y and 3*x
pdl> $x=sequence(100)
pdl> $factor2 = which( ($x % 2) == 0)
pdl> $factor3 = which( ($x % 3) == 0)
pdl> $ii=intersect($factor2, $factor3)
pdl> p $x($ii)
[0 6 12 18 24 30 36 42 48 54 60 66 72 78 84 90 96]0 if successful.
> 0 if there were
ierrswitches in the direction of monotonicity (data still valid).-1 if
dim($x, 0) < 2.-3 if
$xis not strictly increasing.
(The D-array has not been changed in any of these cases.) NOTE: The above errors are checked in the order listed, and following arguments have NOT been validated. EOF }, Doc => <<'EOF', =for ref
Calculate the derivatives of (x,f(x)) using cubic Hermite interpolation.
Calculate the derivatives needed to determine a monotone piecewise cubic Hermite interpolant to the given set of points ($x,$f, where $x is strictly increasing). The resulting set of points - $x,$f,$d, referred to as the cubic Hermite representation - can then be used in other functions, such as "pchip_chfe", "pchip_chfd", and "pchip_chia".
The boundary conditions are compatible with monotonicity, and if the data are only piecewise monotonic, the interpolant will have an extremum at the switch points; for more control over these issues use "pchip_chic".
References:
1. F. N. Fritsch and J. Butland, A method for constructing local monotone piecewise cubic interpolants, SIAM Journal on Scientific and Statistical Computing 5, 2 (June 1984), pp. 300-304.
F. N. Fritsch and R. E. Carlson, Monotone piecewise cubic interpolation, SIAM Journal on Numerical Analysis 17, 2 (April 1980), pp. 238-246. EOF );
pp_def('pchip_chic', Pars => 'sbyte ic(two=2); vc(two=2); mflag(); x(n); f(n); [o]d(n); indx [o]ierr(); [t]h(nless1=CALC($SIZE(n)-1)); [t]slope(nless1);', GenericTypes => $F, RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), const $GENERIC() d1mach = $TFDE(FLT_EPSILON,DBL_EPSILON,LDBL_EPSILON); /* VALIDITY-CHECK ARGUMENTS. */ loop (n=1) %{ if ($x() > $x(n=>n-1)) continue; $ierr() = -1; $CROAK("X-ARRAY NOT STRICTLY INCREASING"); %} PDL_Indx ibeg = $ic(two=>0), iend = $ic(two=>1), n = $SIZE(n); $ierr() = 0; if (PDL_ABS(ibeg) > 5) --($ierr()); if (PDL_ABS(iend) > 5) $ierr() += -2; if ($ierr() < 0) { $ierr() += -3; $CROAK("IC OUT OF RANGE"); } /* FUNCTION DEFINITION IS OK -- GO ON. */ /* SET UP H AND SLOPE ARRAYS. */ loop (nless1) %{ $h() = $x(n=>nless1+1) - $x(n=>nless1); $slope() = $f(n=>nless1+1) - $f(n=>nless1); %} /* SPECIAL CASE N=2 -- USE LINEAR INTERPOLATION. */ if ($SIZE(nless1) <= 1) { $d(n=>0) = $d(n=>1) = $slope(nless1=>0); } else { /* NORMAL CASE (N .GE. 3) . */ /* SET INTERIOR DERIVATIVES AND DEFAULT END CONDITIONS. */ do { /* inline dpchci */ /* Local variables */ $GENERIC() del1 = $slope(nless1=>0); /* SPECIAL CASE N=2 is dealt with in separate branch above */ /* NORMAL CASE (N .GE. 3). */ $GENERIC() del2 = $slope(nless1=>1); /* SET D(1) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */ /* SHAPE-PRESERVING. */ $GENERIC() hsum = $h(nless1=>0) + $h(nless1=>1); $GENERIC() w1 = ($h(nless1=>0) + hsum) / hsum; $GENERIC() w2 = -$h(nless1=>0) / hsum; $d(n=>0) = w1 * del1 + w2 * del2; if ($PCHST($d(n=>0), del1) <= 0.) { $d(n=>0) = 0.; } else if ($PCHST(del1, del2) < 0.) { /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */ $GENERIC() dmax = 3. * del1; if (PDL_ABS($d(n=>0)) > PDL_ABS(dmax)) $d(n=>0) = dmax; } /* LOOP THROUGH INTERIOR POINTS. */ loop (nless1=1) %{ if (nless1 != 1) { hsum = $h(nless1=>nless1-1) + $h(); del1 = del2; del2 = $slope(); } /* SET D(I)=0 UNLESS DATA ARE STRICTLY MONOTONIC. */ $d(n=>nless1) = 0.; if ($PCHST(del1, del2) <= 0.) continue; /* USE BRODLIE MODIFICATION OF BUTLAND FORMULA. */ $GENERIC() hsumt3 = hsum + hsum + hsum; w1 = (hsum + $h(nless1=>nless1-1)) / hsumt3; w2 = (hsum + $h()) / hsumt3; /* Computing MAX */ $GENERIC() dmax = PDLMAX(PDL_ABS(del1),PDL_ABS(del2)); /* Computing MIN */ $GENERIC() dmin = PDLMIN(PDL_ABS(del1),PDL_ABS(del2)); $GENERIC() drat1 = del1 / dmax, drat2 = del2 / dmax; $d(n=>nless1) = dmin / (w1 * drat1 + w2 * drat2); %} /* SET D(N) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */ /* SHAPE-PRESERVING. */ w1 = -$h(nless1=>n-2) / hsum; w2 = ($h(nless1=>n-2) + hsum) / hsum; $d(n=>n-1) = w1 * del1 + w2 * del2; if ($PCHST($d(n=>n-1), del2) <= 0.) { $d(n=>n-1) = 0.; } else if ($PCHST(del1, del2) < 0.) { /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */ $GENERIC() dmax = 3. * del2; if (PDL_ABS($d(n=>n-1)) > PDL_ABS(dmax)) $d(n=>n-1) = dmax; } } while (0); /* end inline dpchci */ /* SET DERIVATIVES AT POINTS WHERE MONOTONICITY SWITCHES DIRECTION. */ if ($mflag() != 0.) { do { /* inline dpchcs */ /* ***PURPOSE Adjusts derivative values for DPCHIC */ /* DPCHCS: DPCHIC Monotonicity Switch Derivative Setter. */ /* Called by DPCHIC to adjust the values of D in the vicinity of a */ /* switch in direction of monotonicity, to produce a more "visually */ /* pleasing" curve than that given by DPCHIM . */ static const $GENERIC() fudge = 4.; /* Local variables */ PDL_Indx k; $GENERIC() del[3], fact, dfmx; $GENERIC() dext, dfloc, slmax, wtave[2]; /* INITIALIZE. */ /* LOOP OVER SEGMENTS. */ loop (nless1=1) %{ $GENERIC() dtmp = $PCHST($slope(nless1=>nless1-1), $slope()); if (dtmp > 0.) { continue; } if (dtmp != 0.) { /* ....... SLOPE SWITCHES MONOTONICITY AT I-TH POINT ..................... */ /* DO NOT CHANGE D IF 'UP-DOWN-UP'. */ if (nless1 > 1) { if ($PCHST($slope(nless1=>nless1-2), $slope()) > 0.) continue; /* -------------------------- */ } if (nless1 < $SIZE(nless1)-1 && $PCHST($slope(nless1=>nless1+1), $slope(nless1=>nless1-1)) > 0.) continue; /* ---------------------------- */ /* ....... COMPUTE PROVISIONAL VALUE FOR D(1,I). */ dext = $h() / ($h(nless1=>nless1-1) + $h()) * $slope(nless1=>nless1-1) + $h(nless1=>nless1-1) / ($h(nless1=>nless1-1) + $h()) * $slope(); /* ....... DETERMINE WHICH INTERVAL CONTAINS THE EXTREMUM. */ dtmp = $PCHST(dext, $slope(nless1=>nless1-1)); if (dtmp == 0) { continue; } if (dtmp < 0.) { /* DEXT AND SLOPE(I-1) HAVE OPPOSITE SIGNS -- */ /* EXTREMUM IS IN (X(I-1),X(I)). */ k = nless1; /* SET UP TO COMPUTE NEW VALUES FOR D(1,I-1) AND D(1,I). */ wtave[1] = dext; if (k > 1) { wtave[0] = $h(nless1=>k-1) / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-2) + $h(nless1=>k-2) / ($h(nless1=>k-2) + $h(nless1=>k)) * $slope(nless1=>k-1); } } else { /* DEXT AND SLOPE(I) HAVE OPPOSITE SIGNS -- */ /* EXTREMUM IS IN (X(I),X(I+1)). */ k = nless1 + 1; /* SET UP TO COMPUTE NEW VALUES FOR D(1,I) AND D(1,I+1). */ wtave[0] = dext; if (k < nless1) { wtave[1] = $h(nless1=>k) / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k-1) + $h(nless1=>k-1) / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k); } } } else { /* ....... AT LEAST ONE OF SLOPE(I-1) AND SLOPE(I) IS ZERO -- */ /* CHECK FOR FLAT-TOPPED PEAK ....................... */ if (nless1 == $SIZE(nless1)-1 || $PCHST($slope(nless1=>nless1-1), $slope(nless1=>nless1+1)) >= 0.) continue; /* ----------------------------- */ /* WE HAVE FLAT-TOPPED PEAK ON (X(I),X(I+1)). */ k = nless1+1; /* SET UP TO COMPUTE NEW VALUES FOR D(1,I) AND D(1,I+1). */ wtave[0] = $h(nless1=>k-1) / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-2) + $h(nless1=>k-2) / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-1); wtave[1] = $h(nless1=>k) / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k-1) + $h(nless1=>k-1) / ( $h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k); } /* ....... AT THIS POINT WE HAVE DETERMINED THAT THERE WILL BE AN EXTREMUM */ /* ON (X(K),X(K+1)), WHERE K=I OR I-1, AND HAVE SET ARRAY WTAVE-- */ /* WTAVE(1) IS A WEIGHTED AVERAGE OF SLOPE(K-1) AND SLOPE(K), */ /* IF K.GT.1 */ /* WTAVE(2) IS A WEIGHTED AVERAGE OF SLOPE(K) AND SLOPE(K+1), */ /* IF K.LT.N-1 */ slmax = PDL_ABS($slope(nless1=>k-1)); if (k > 1) { /* Computing MAX */ slmax = PDLMAX(slmax,PDL_ABS($slope(nless1=>k-2))); } if (k < nless1) { /* Computing MAX */ slmax = PDLMAX(slmax,PDL_ABS($slope(nless1=>k))); } if (k > 1) { del[0] = $slope(nless1=>k-2) / slmax; } del[1] = $slope(nless1=>k-1) / slmax; if (k < nless1) { del[2] = $slope(nless1=>k) / slmax; } if (k > 1 && k < nless1) { /* NORMAL CASE -- EXTREMUM IS NOT IN A BOUNDARY INTERVAL. */ fact = fudge * PDL_ABS(del[2] * (del[0] - del[1]) * (wtave[1] / slmax)); $d(n=>k-1) += PDLMIN(fact,1.) * (wtave[0] - $d(n=>k-1)); fact = fudge * PDL_ABS(del[0] * (del[2] - del[1]) * (wtave[0] / slmax)); $d(n=>k) += PDLMIN(fact,1.) * (wtave[1] - $d(n=>k)); } else { /* SPECIAL CASE K=1 (WHICH CAN OCCUR ONLY IF I=2) OR */ /* K=NLESS1 (WHICH CAN OCCUR ONLY IF I=NLESS1). */ fact = fudge * PDL_ABS(del[1]); $d(n=>nless1) = PDLMIN(fact,1.) * wtave[nless1+1 - k]; /* NOTE THAT I-K+1 = 1 IF K=I (=NLESS1), */ /* I-K+1 = 2 IF K=I-1(=1). */ } /* ....... ADJUST IF NECESSARY TO LIMIT EXCURSIONS FROM DATA. */ if ($mflag() <= 0.) { continue; } dfloc = $h(nless1=>k-1) * PDL_ABS($slope(nless1=>k-1)); if (k > 1) { /* Computing MAX */ dfloc = PDLMAX(dfloc,$h(nless1=>k-2) * PDL_ABS($slope(nless1=>k-2))); } if (k < nless1) { /* Computing MAX */ dfloc = PDLMAX(dfloc,$h(nless1=>k) * PDL_ABS($slope(nless1=>k))); } dfmx = $mflag() * dfloc; PDL_Indx indx = nless1 - k; /* INDX = 1 IF K=I, 2 IF K=I-1. */ /* --------------------------------------------------------------- */ do { /* inline dpchsw */ /* NOTATION AND GENERAL REMARKS. */ /* RHO IS THE RATIO OF THE DATA SLOPE TO THE DERIVATIVE BEING TESTED. */ /* LAMBDA IS THE RATIO OF D2 TO D1. */ /* THAT = T-HAT(RHO) IS THE NORMALIZED LOCATION OF THE EXTREMUM. */ /* PHI IS THE NORMALIZED VALUE OF P(X)-F1 AT X = XHAT = X-HAT(RHO), */ /* WHERE THAT = (XHAT - X1)/H . */ /* THAT IS, P(XHAT)-F1 = D*H*PHI, WHERE D=D1 OR D2. */ /* SIMILARLY, P(XHAT)-F2 = D*H*(PHI-RHO) . */ /* Local variables */ $GENERIC() cp, nu, phi, rho, hphi, that, sigma, small; $GENERIC() lambda, radcal; $GENERIC() d1 = $d(n=>k-1), d2 = $d(n=>k), h2 = $h(nless1=>k-1), slope2 = $slope(nless1=>k-1); /* Initialized data */ static const $GENERIC() fact = 100.; /* THIRD SHOULD BE SLIGHTLY LESS THAN 1/3. */ static const $GENERIC() third = .33333; /* SMALL SHOULD BE A FEW ORDERS OF MAGNITUDE GREATER THAN MACHEPS. */ small = fact * d1mach; /* DO MAIN CALCULATION. */ if (d1 == 0.) { /* SPECIAL CASE -- D1.EQ.ZERO . */ /* IF D2 IS ALSO ZERO, THIS ROUTINE SHOULD NOT HAVE BEEN CALLED. */ if (d2 == 0.) { $ierr() = -1; $CROAK("D1 AND/OR D2 INVALID"); } rho = slope2 / d2; /* EXTREMUM IS OUTSIDE INTERVAL WHEN RHO .GE. 1/3 . */ if (rho >= third) { $ierr() = 0; break; } that = 2. * (3. * rho - 1.) / (3. * (2. * rho - 1.)); /* Computing 2nd power */ phi = that * that * ((3. * rho - 1.) / 3.); /* CONVERT TO DISTANCE FROM F2 IF IEXTRM.NE.1 . */ if (indx != 3) { phi -= rho; } /* TEST FOR EXCEEDING LIMIT, AND ADJUST ACCORDINGLY. */ hphi = h2 * PDL_ABS(phi); if (hphi * PDL_ABS(d2) > dfmx) { /* AT THIS POINT, HPHI.GT.0, SO DIVIDE IS OK. */ d2 = $SIGN(dfmx / hphi, d2); } } else { rho = slope2 / d1; lambda = -(d2) / d1; if (d2 == 0.) { /* SPECIAL CASE -- D2.EQ.ZERO . */ /* EXTREMUM IS OUTSIDE INTERVAL WHEN RHO .GE. 1/3 . */ if (rho >= third) { $ierr() = 0; break; } cp = 2. - 3. * rho; nu = 1. - 2. * rho; that = 1. / (3. * nu); } else { if (lambda <= 0.) { $ierr() = -1; $CROAK("D1 AND/OR D2 INVALID"); } /* NORMAL CASE -- D1 AND D2 BOTH NONZERO, OPPOSITE SIGNS. */ nu = 1. - lambda - 2. * rho; sigma = 1. - rho; cp = nu + sigma; if (PDL_ABS(nu) > small) { /* Computing 2nd power */ radcal = (nu - (2. * rho + 1.)) * nu + sigma * sigma; if (radcal < 0.) { $ierr() = -2; $CROAK("NEGATIVE RADICAL"); } that = (cp - sqrt(radcal)) / (3. * nu); } else { that = 1. / (2. * sigma); } } phi = that * ((nu * that - cp) * that + 1.); /* CONVERT TO DISTANCE FROM F2 IF IEXTRM.NE.1 . */ if (indx != 3) { phi -= rho; } /* TEST FOR EXCEEDING LIMIT, AND ADJUST ACCORDINGLY. */ hphi = h2 * PDL_ABS(phi); if (hphi * PDL_ABS(d1) > dfmx) { /* AT THIS POINT, HPHI.GT.0, SO DIVIDE IS OK. */ d1 = $SIGN(dfmx / hphi, d1); d2 = -lambda * d1; } } $ierr() = 0; } while (0); /* end inline dpchsw */ /* --------------------------------------------------------------- */ if ($ierr() != 0) { break; } %} /* ....... END OF SEGMENT LOOP. */ } while (0); /* end inline dpchcs */ } } /* SET END CONDITIONS. */ if (ibeg == 0 && iend == 0) continue; /* ------------------------------------------------------- */ do { /* inline dpchce */ /* Local variables */ PDL_Indx j, k, ibeg = $ic(two=>0), iend = $ic(two=>1); $GENERIC() stemp[3], xtemp[4]; /* SET TO DEFAULT BOUNDARY CONDITIONS IF N IS TOO SMALL. */ if (PDL_ABS(ibeg) > n) ibeg = 0; if (PDL_ABS(iend) > n) iend = 0; /* TREAT BEGINNING BOUNDARY CONDITION. */ if (ibeg != 0) { k = PDL_ABS(ibeg); if (k == 1) { /* BOUNDARY VALUE PROVIDED. */ $d(n=>0) = $vc(two=>0); } else if (k == 2) { /* BOUNDARY SECOND DERIVATIVE PROVIDED. */ $d(n=>0) = 0.5 * (3. * $slope(nless1=>0) - $d(n=>1) - 0.5 * $vc(two=>0) * $h(nless1=>0)); } else if (k < 5) { /* USE K-POINT DERIVATIVE FORMULA. */ /* PICK UP FIRST K POINTS, IN REVERSE ORDER. */ for (j = 0; j < k; ++j) { PDL_Indx index = k - j; /* INDEX RUNS FROM K DOWN TO 1. */ xtemp[j] = $x(n=>index+1); if (j < k-1) { stemp[j] = $slope(nless1=>index); } } /* ----------------------------- */ $PCHDF(k, xtemp, stemp, $d(n=>0)); /* ----------------------------- */ } else { /* USE 'NOT A KNOT' CONDITION. */ $d(n=>0) = (3. * ($h(nless1=>0) * $slope(nless1=>1) + $h(nless1=>1) * $slope(nless1=>0)) - 2. * ($h(nless1=>0) + $h(nless1=>1)) * $d(n=>1) - $h(nless1=>0) * $d(n=>2)) / $h(nless1=>1); } /* CHECK D(1,1) FOR COMPATIBILITY WITH MONOTONICITY. */ if (ibeg <= 0) { if ($slope(nless1=>0) == 0.) { if ($d(n=>0) != 0.) { $d(n=>0) = 0.; ++($ierr()); } } else if ($PCHST($d(n=>0), $slope(nless1=>0)) < 0.) { $d(n=>0) = 0.; ++($ierr()); } else if (PDL_ABS($d(n=>0)) > 3. * PDL_ABS($slope(nless1=>0))) { $d(n=>0) = 3. * $slope(nless1=>0); ++($ierr()); } } } /* TREAT END BOUNDARY CONDITION. */ if (iend == 0) break; k = PDL_ABS(iend); if (k == 1) { /* BOUNDARY VALUE PROVIDED. */ $d(n=>n-1) = $vc(two=>1); } else if (k == 2) { /* BOUNDARY SECOND DERIVATIVE PROVIDED. */ $d(n=>n-1) = 0.5 * (3. * $slope(nless1=>n-2) - $d(n=>n-2) + 0.5 * $vc(two=>1) * $h(nless1=>n-2)); } else if (k < 5) { /* USE K-POINT DERIVATIVE FORMULA. */ /* PICK UP LAST K POINTS. */ for (j = 0; j < k; ++j) { PDL_Indx index = n - k + j; /* INDEX RUNS FROM N+1-K UP TO N. */ xtemp[j] = $x(n=>index); if (j < k-1) { stemp[j] = $slope(nless1=>index); } } /* ----------------------------- */ $PCHDF(k, xtemp, stemp, $d(n=>n-1)); /* ----------------------------- */ } else { /* USE 'NOT A KNOT' CONDITION. */ $d(n=>n-1) = (3. * ($h(nless1=>n-2) * $slope(nless1=>n-3) + $h(nless1=>n-3) * $slope(nless1=>n-2)) - 2. * ($h(nless1=>n-2) + $h(nless1=>n-3)) * $d(n=>n-2) - $h(nless1=>n-2) * $d(n=>n-3)) / $h(nless1=>n-3); } if (iend > 0) break; /* CHECK D(1,N) FOR COMPATIBILITY WITH MONOTONICITY. */ if ($slope(nless1=>n-2) == 0.) { if ($d(n=>n-1) != 0.) { $d(n=>n-1) = 0.; $ierr() += 2; } } else if ($PCHST($d(n=>n-1), $slope(nless1=>n-2)) < 0.) { $d(n=>n-1) = 0.; $ierr() += 2; } else if (PDL_ABS($d(n=>n-1)) > 3. * PDL_ABS($slope(nless1=>n-2))) { $d(n=>n-1) = 3. * $slope(nless1=>n-2); $ierr() += 2; } } while (0); /* end inlined dpchce */ /* ------------------------------------------------------- */ EOF ParamDesc => { ic => <<'EOF', The first and second elements of $ic determine the boundary conditions at the start and end of the data respectively. If the value is 0, then the default condition, as used by "pchip_chim", is adopted. If greater than zero, no adjustment for monotonicity is made, otherwise if less than zero the derivative will be adjusted. The allowed magnitudes for ic(0) are:
1 if first derivative at
x(0)is given invc(0).2 if second derivative at
x(0)is given invc(0).3 to use the 3-point difference formula for
d(0). (Reverts to the default b.c. ifn < 3)4 to use the 4-point difference formula for
d(0). (Reverts to the default b.c. ifn < 4)5 to set
d(0)so that the second derivative is continuous atx(1). (Reverts to the default b.c. ifn < 4) This option is somewhat analogous to the "not a knot" boundary condition provided by DPCHSP.
The values for ic(1) are the same as above, except that the first-derivative value is stored in vc(1) for cases 1 and 2. The values of $vc need only be set if options 1 or 2 are chosen for $ic. NOTES:
Only in case
$ic(n)< 0 is it guaranteed that the interpolant will be monotonic in the first interval. If the returned value of D(start_or_end) lies between zero and 3*SLOPE(start_or_end), the interpolant will be monotonic. This is NOT checked if$ic(n)> 0.If
$ic(n)< 0 and D(0) had to be changed to achieve monotonicity, a warning error is returned.
Set $mflag = 0 if interpolant is required to be monotonic in each interval, regardless of monotonicity of data. This causes $d to be set to 0 at all switch points. NOTES:
This will cause D to be set to zero at all switch points, thus forcing extrema there.
The result of using this option with the default boundary conditions will be identical to using DPCHIM, but will generally cost more compute time. This option is provided only to facilitate comparison of different switch and/or boundary conditions.
X(I-1) .LT. X(I), I = 2(1)N.(Error return if not.) EOF f => <<'EOF', array of dependent variable values to be interpolated. F(I) is value corresponding to X(I). EOF d => <<'EOF', array of derivative values at the data points. These values will determine a monotone cubic Hermite function on each subinterval on which the data are monotonic, except possibly adjacent to switches in monotonicity. The value corresponding to X(I) is stored in D(I). No other entries in D are changed. EOF ierr => <<'EOF', Error status:
0 if successful.
1 if
ic(0) < 0andd(0)had to be adjusted for monotonicity.2 if
ic(1) < 0andd(n-1)had to be adjusted for monotonicity.3 if both 1 and 2 are true.
-1 if
n < 2.-3 if
$xis not strictly increasing.-4 if
abs(ic(0)) > 5.-5 if
abs(ic(1)) > 5.-6 if both -4 and -5 are true.
-7 if
nwk < 2*(n-1).
(The D-array has not been changed in any of these cases.) NOTE: The above errors are checked in the order listed, and following arguments have NOT been validated. EOF }, Doc => <<'EOF', =for ref
Set derivatives needed to determine a piecewise monotone piecewise cubic Hermite interpolant to given data. User control is available over boundary conditions and/or treatment of points where monotonicity switches direction.
Calculate the derivatives needed to determine a piecewise monotone piecewise cubic interpolant to the data given in ($x,$f, where $x is strictly increasing). Control over the boundary conditions is given by the $ic and $vc ndarrays, and the value of $mflag determines the treatment of points where monotonicity switches direction. A simpler, more restricted, interface is available using "pchip_chim". The resulting piecewise cubic Hermite function may be evaluated by "pchip_chfe" or "pchip_chfd".
References:
1. F. N. Fritsch, Piecewise Cubic Hermite Interpolation Package, Report UCRL-87285, Lawrence Livermore National Laboratory, July 1982. [Poster presented at the SIAM 30th Anniversary Meeting, 19-23 July 1982.]
2. F. N. Fritsch and J. Butland, A method for constructing local monotone piecewise cubic interpolants, SIAM Journal on Scientific and Statistical Computing 5, 2 (June 1984), pp. 300-304.
3. F. N. Fritsch and R. E. Carlson, Monotone piecewise cubic interpolation, SIAM Journal on Numerical Analysis 17, 2 (April 1980), pp. 238-246. EOF );
pp_def('pchip_chsp', Pars => 'sbyte ic(two=2); vc(two=2); x(n); f(n); [o]d(n); indx [o]ierr(); [t]dx(n); [t]dy_dx(n); ', GenericTypes => $F, RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), /* SINGULAR SYSTEM. */ /* *** THEORETICALLY, THIS CAN ONLY OCCUR IF SUCCESSIVE X-VALUES *** */ /* *** ARE EQUAL, WHICH SHOULD ALREADY HAVE BEEN CAUGHT (IERR=-3). *** */ #define dpchsp_singular(x, ind) \ $ierr() = -8; $CROAK("SINGULAR LINEAR SYSTEM(" #x ") at %td", ind); /* Local variables */ $GENERIC() stemp[3], xtemp[4]; PDL_Indx n = $SIZE(n), nm1 = n - 1; /* VALIDITY-CHECK ARGUMENTS. */ loop (n=1) %{ if ($x() > $x(n=>n-1)) continue; $ierr() = -1; $CROAK("X-ARRAY NOT STRICTLY INCREASING"); %} PDL_Indx ibeg = $ic(two=>0), iend = $ic(two=>1), j; $ierr() = 0; if (PDL_ABS(ibeg) > 5) --($ierr()); if (PDL_ABS(iend) > 5) $ierr() += -2; if ($ierr() < 0) { $ierr() += -3; $CROAK("IC OUT OF RANGE"); } /* FUNCTION DEFINITION IS OK -- GO ON. */ /* COMPUTE FIRST DIFFERENCES OF X SEQUENCE AND STORE IN WK(1,.). ALSO, */ /* COMPUTE FIRST DIVIDED DIFFERENCE OF DATA AND STORE IN WK(2,.). */ loop (n=1) %{ $dx() = $x() - $x(n=>n-1); $dy_dx() = ($f() - $f(n=>n-1)) / $dx(); %} /* SET TO DEFAULT BOUNDARY CONDITIONS IF N IS TOO SMALL. */ if (ibeg > n) { ibeg = 0; } if (iend > n) { iend = 0; } /* SET UP FOR BOUNDARY CONDITIONS. */ if (ibeg == 1 || ibeg == 2) { $d(n=>0) = $vc(two=>0); } else if (ibeg > 2) { /* PICK UP FIRST IBEG POINTS, IN REVERSE ORDER. */ for (j = 0; j < ibeg; ++j) { PDL_Indx index = ibeg - j + 1; /* INDEX RUNS FROM IBEG DOWN TO 1. */ xtemp[j] = $x(n=>index); if (j < ibeg-1) stemp[j] = $dy_dx(n=>index); } /* -------------------------------- */ $PCHDF(ibeg, xtemp, stemp, $d(n=>0)); /* -------------------------------- */ ibeg = 1; } if (iend == 1 || iend == 2) { $d(n=>n-1) = $vc(two=>1); } else if (iend > 2) { /* PICK UP LAST IEND POINTS. */ for (j = 0; j < iend; ++j) { PDL_Indx index = n - iend + j; /* INDEX RUNS FROM N+1-IEND UP TO N. */ xtemp[j] = $x(n=>index); if (j < iend-1) stemp[j] = $dy_dx(n=>index+1); } /* -------------------------------- */ $PCHDF(iend, xtemp, stemp, $d(n=>n-1)); /* -------------------------------- */ iend = 1; } /* --------------------( BEGIN CODING FROM CUBSPL )-------------------- */ /* **** A TRIDIAGONAL LINEAR SYSTEM FOR THE UNKNOWN SLOPES S(J) OF */ /* F AT X(J), J=1,...,N, IS GENERATED AND THEN SOLVED BY GAUSS ELIM- */ /* INATION, WITH S(J) ENDING UP IN D(1,J), ALL J. */ /* WK(1,.) AND WK(2,.) ARE USED FOR TEMPORARY STORAGE. */ /* CONSTRUCT FIRST EQUATION FROM FIRST BOUNDARY CONDITION, OF THE FORM */ /* WK(2,1)*S(1) + WK(1,1)*S(2) = D(1,1) */ if (ibeg == 0) { if (n == 2) { /* NO CONDITION AT LEFT END AND N = 2. */ $dy_dx(n=>0) = 1.; $dx(n=>0) = 1.; $d(n=>0) = 2. * $dy_dx(n=>1); } else { /* NOT-A-KNOT CONDITION AT LEFT END AND N .GT. 2. */ $dy_dx(n=>0) = $dx(n=>2); $dx(n=>0) = $dx(n=>1) + $dx(n=>2); /* Computing 2nd power */ $d(n=>0) = (($dx(n=>1) + 2. * $dx(n=>0)) * $dy_dx(n=>1) * $dx(n=>2) + $dx(n=>1) * $dx(n=>1) * $dy_dx(n=>2)) / $dx(n=>0); } } else if (ibeg == 1) { /* SLOPE PRESCRIBED AT LEFT END. */ $dy_dx(n=>0) = 1.; $dx(n=>0) = 0.; } else { /* SECOND DERIVATIVE PRESCRIBED AT LEFT END. */ $dy_dx(n=>0) = 2.; $dx(n=>0) = 1.; $d(n=>0) = 3. * $dy_dx(n=>1) - 0.5 * $dx(n=>1) * $d(n=>0); } /* IF THERE ARE INTERIOR KNOTS, GENERATE THE CORRESPONDING EQUATIONS AND */ /* CARRY OUT THE FORWARD PASS OF GAUSS ELIMINATION, AFTER WHICH THE J-TH */ /* EQUATION READS WK(2,J)*S(J) + WK(1,J)*S(J+1) = D(1,J). */ if (n > 2) { loop (n=1:-1) %{ if ($dy_dx(n=>n-1) == 0.) { dpchsp_singular(1, n-1); } $GENERIC() g = -$dx(n=>n+1) / $dy_dx(n=>n-1); $d() = g * $d(n=>n-1) + 3. * ($dx() * $dy_dx(n=>n+1) + $dx(n=>n+1) * $dy_dx()); $dy_dx() = g * $dx(n=>n-1) + 2. * ($dx() + $dx(n=>n+1)); %} } /* CONSTRUCT LAST EQUATION FROM SECOND BOUNDARY CONDITION, OF THE FORM */ /* (-G*WK(2,N-1))*S(N-1) + WK(2,N)*S(N) = D(1,N) */ /* IF SLOPE IS PRESCRIBED AT RIGHT END, ONE CAN GO DIRECTLY TO BACK- */ /* SUBSTITUTION, SINCE ARRAYS HAPPEN TO BE SET UP JUST RIGHT FOR IT */ /* AT THIS POINT. */ if (iend != 1) { if (iend == 0 && n == 2 && ibeg == 0) { /* NOT-A-KNOT AT RIGHT ENDPOINT AND AT LEFT ENDPOINT AND N = 2. */ $d(n=>1) = $dy_dx(n=>1); } else { $GENERIC() g; if (iend == 0) { if (n == 2 || (n == 3 && ibeg == 0)) { /* EITHER (N=3 AND NOT-A-KNOT ALSO AT LEFT) OR (N=2 AND *NOT* */ /* NOT-A-KNOT AT LEFT END POINT). */ $d(n=>n-1) = 2. * $dy_dx(n=>n-1); $dy_dx(n=>n-1) = 1.; if ($dy_dx(n=>n-2) == 0.) { dpchsp_singular(2, n-2); } g = -1. / $dy_dx(n=>n-2); } else { /* NOT-A-KNOT AND N .GE. 3, AND EITHER N.GT.3 OR ALSO NOT-A- */ /* KNOT AT LEFT END POINT. */ g = $dx(n=>n-2) + $dx(n=>n-1); /* DO NOT NEED TO CHECK FOLLOWING DENOMINATORS (X-DIFFERENCES). */ /* Computing 2nd power */ $GENERIC() dtmp = $dx(n=>n-1); $d(n=>n-1) = (($dx(n=>n-1) + 2. * g) * $dy_dx(n=>n-1) * $dx(n=>n-2) + dtmp * dtmp * ($f(n=>n-2) - $f(n=>n-3)) / $dx(n=>n-2)) / g; if ($dy_dx(n=>n-2) == 0.) { dpchsp_singular(3, n-2); } g /= -$dy_dx(n=>n-2); $dy_dx(n=>n-1) = $dx(n=>n-2); } } else { /* SECOND DERIVATIVE PRESCRIBED AT RIGHT ENDPOINT. */ $d(n=>n-1) = 3. * $dy_dx(n=>n-1) + 0.5 * $dx(n=>n-1) * $d(n=>n-1); $dy_dx(n=>n-1) = 2.; if ($dy_dx(n=>n-2) == 0.) { dpchsp_singular(4, n-2); } g = -1. / $dy_dx(n=>n-2); } /* COMPLETE FORWARD PASS OF GAUSS ELIMINATION. */ $dy_dx(n=>n-1) = g * $dx(n=>n-2) + $dy_dx(n=>n-1); if ($dy_dx(n=>n-1) == 0.) { dpchsp_singular(5, n-1); } $d(n=>n-1) = (g * $d(n=>n-2) + $d(n=>n-1)) / $dy_dx(n=>n-1); } } /* CARRY OUT BACK SUBSTITUTION */ loop (n=nm1-1::-1) %{ if ($dy_dx() == 0.) { dpchsp_singular(6, n); } $d() = ($d() - $dx() * $d(n=>n+1)) / $dy_dx(); %} /* --------------------( END CODING FROM CUBSPL )-------------------- */ #undef dpchsp_singular EOF ParamDesc => { ic => <<'EOF', The first and second elements determine the boundary conditions at the start and end of the data respectively. The allowed values for ic(0) are:
0 to set
d(0)so that the third derivative is continuous atx(1).1 if first derivative at
x(0)is given invc(0).2 if second derivative at
x(0) is given invc(0).3 to use the 3-point difference formula for
d(0). (Reverts to the default b.c. ifn < 3.)4 to use the 4-point difference formula for
d(0). (Reverts to the default b.c. ifn < 4.)
The values for ic(1) are the same as above, except that the first-derivative value is stored in vc(1) for cases 1 and 2. The values of $vc need only be set if options 1 or 2 are chosen for $ic.
NOTES: For the "natural" boundary condition, use IC(n)=2 and VC(n)=0. EOF vc => 'See ic for details', ierr => <<'EOF', Error status:
0 if successful.
-1 if
dim($x, 0) < 2.-3 if
$xis not strictly increasing.-4 if
ic(0) < 0oric(0) > 4.-5 if
ic(1) < 0oric(1) > 4.-6 if both of the above are true.
-7 if
nwk < 2*n.NOTE: The above errors are checked in the order listed, and following arguments have NOT been validated. (The D-array has not been changed in any of these cases.)
-8 in case of trouble solving the linear system for the interior derivative values. (The D-array may have been changed in this case. Do NOT use it!)
Calculate the derivatives of (x,f(x)) using cubic spline interpolation.
Computes the Hermite representation of the cubic spline interpolant to the data given in ($x,$f), with the specified boundary conditions. Control over the boundary conditions is given by the $ic and $vc ndarrays. The resulting values - $x,$f,$d - can be used in all the functions which expect a cubic Hermite function, including "pchip_bvalu".
References: Carl de Boor, A Practical Guide to Splines, Springer-Verlag, New York, 1978, pp. 53-59. EOF );
pp_def('pchip_chfd', Pars => 'x(n); f(n); d(n); xe(ne); [o] fe(ne); [o] de(ne); indx [o] ierr(); int [o] skip()', RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); if ($SIZE(ne) < 1) $CROAK("NUMBER OF EVALUATION POINTS LESS THAN ONE"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), $CHFD(1); EOF GenericTypes => $F, ParamDesc => { skip => <<'EOF', Set to 1 to skip checks on the input data. This will save time in case these checks have already been performed (say, in "pchip_chim" or "pchip_chic"). Will be set to TRUE on normal return. EOF xe => <<'EOF', array of points at which the functions are to be evaluated. NOTES:
The evaluation will be most efficient if the elements of XE are increasing relative to X; that is, XE(J) .GE. X(I) implies XE(K) .GE. X(I), all K.GE.J .
If any of the XE are outside the interval [X(1),X(N)], values are extrapolated from the nearest extreme cubic, and a warning error is returned.
0 if successful.
>0 if extrapolation was performed at
ierrpoints (data still valid).-1 if
dim($x, 0) < 2-3 if
$xis not strictly increasing.-4 if
dim($xe, 0) < 1.-5 if an error has occurred in a lower-level routine, which should never happen.
Evaluate a piecewise cubic Hermite function and its first derivative at an array of points. May be used by itself for Hermite interpolation, or as an evaluator for DPCHIM or DPCHIC.
Given a piecewise cubic Hermite function - such as from "pchip_chim" - evaluate the function ($fe) and derivative ($de) at a set of points ($xe). If function values alone are required, use "pchip_chfe". EOF );
pp_def('pchip_chfe', Pars => 'x(n); f(n); d(n); xe(ne); [o] fe(ne); indx [o] ierr(); int [o] skip()', RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); if ($SIZE(ne) < 1) $CROAK("NUMBER OF EVALUATION POINTS LESS THAN ONE"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), $CHFD(0); EOF GenericTypes => $F, ParamDesc => { x => <<'EOF', array of independent variable values. The elements of X must be strictly increasing:
X(I-1) .LT. X(I), I = 2(1)N.(Error return if not.) EOF f => <<'EOF', array of function values. F(I) is the value corresponding to X(I). EOF d => <<'EOF', array of derivative values. D(I) is the value corresponding to X(I). EOF skip => <<'EOF', Set to 1 to skip checks on the input data. This will save time in case these checks have already been performed (say, in "pchip_chim" or "pchip_chic"). Will be set to TRUE on normal return. EOF xe => <<'EOF', array of points at which the function is to be evaluated. NOTES:
The evaluation will be most efficient if the elements of XE are increasing relative to X; that is, XE(J) .GE. X(I) implies XE(K) .GE. X(I), all K.GE.J .
If any of the XE are outside the interval [X(1),X(N)], values are extrapolated from the nearest extreme cubic, and a warning error is returned.
0 if successful.
>0 if extrapolation was performed at
ierrpoints (data still valid).-1 if
dim($x, 0) < 2-3 if
$xis not strictly increasing.-4 if
dim($xe, 0) < 1.
(The FE-array has not been changed in any of these cases.) NOTE: The above errors are checked in the order listed, and following arguments have NOT been validated. EOF }, Doc => <<'EOF', =for ref
Evaluate a piecewise cubic Hermite function at an array of points. May be used by itself for Hermite interpolation, or as an evaluator for "pchip_chim" or "pchip_chic".
Given a piecewise cubic Hermite function - such as from "pchip_chim" - evaluate the function ($fe) at a set of points ($xe). If derivative values are also required, use "pchip_chfd". EOF );
pp_def('pchip_chia', Pars => 'x(n); f(n); d(n); la(); lb(); [o]ans(); indx [o]ierr(); int [o]skip()', GenericTypes => $F, RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), PDL_Indx ia, ib, il; $GENERIC() a = $la(), b = $lb(), xa, xb; PDL_Indx ir, n = $SIZE(n); $GENERIC() value = 0.; if (!$skip()) { loop (n=1) %{ if ($x() > $x(n=>n-1)) continue; $ierr() = -1; $CROAK("X-ARRAY NOT STRICTLY INCREASING"); %} } /* FUNCTION DEFINITION IS OK, GO ON. */ $skip() = 1; $ierr() = 0; if (a < $x(n=>0) || a > $x(n=>n-1)) { ++($ierr()); } if (b < $x(n=>0) || b > $x(n=>n-1)) { $ierr() += 2; } /* COMPUTE INTEGRAL VALUE. */ if (a != b) { xa = PDLMIN(a,b); xb = PDLMAX(a,b); if (xb <= $x(n=>1)) { /* INTERVAL IS TO LEFT OF X(2), SO USE FIRST CUBIC. */ /* --------------------------------------- */ $CHFIE($x(n=>0), $x(n=>1), $f(n=>0), $f(n=>1), $d(n=>0), $d(n=>1), a, b, value); /* --------------------------------------- */ } else if (xa >= $x(n=>n-2)) { /* INTERVAL IS TO RIGHT OF X(N-1), SO USE LAST CUBIC. */ /* ------------------------------------------ */ $CHFIE($x(n=>n-2), $x(n=>n-1), $f(n=>n-2), $f(n=>n-1), $d(n=>n-2), $d(n=>n-1), a, b, value); /* ------------------------------------------ */ } else { /* 'NORMAL' CASE -- XA.LT.XB, XA.LT.X(N-1), XB.GT.X(2). */ /* ......LOCATE IA AND IB SUCH THAT */ /* X(IA-1).LT.XA.LE.X(IA).LE.X(IB).LE.XB.LE.X(IB+1) */ ia = 0; loop (n=:-1) %{ if (xa > $x()) ia = n + 1; %} /* IA = 1 IMPLIES XA.LT.X(1) . OTHERWISE, */ /* IA IS LARGEST INDEX SUCH THAT X(IA-1).LT.XA,. */ ib = n - 1; loop (n=:ia:-1) %{ if (xb < $x()) ib = n - 1; %} /* IB = N IMPLIES XB.GT.X(N) . OTHERWISE, */ /* IB IS SMALLEST INDEX SUCH THAT XB.LT.X(IB+1) . */ /* ......COMPUTE THE INTEGRAL. */ if (ib <= ia) { /* THIS MEANS IB = IA-1 AND */ /* (A,B) IS A SUBSET OF (X(IB),X(IA)). */ /* ------------------------------------------- */ $CHFIE($x(n=>ib), $x(n=>ia), $f(n=>ib), $f(n=>ia), $d(n=>ib), $d(n=>ia), a, b, value); /* ------------------------------------------- */ } else { /* FIRST COMPUTE INTEGRAL OVER (X(IA),X(IB)). */ /* (Case (IB .EQ. IA) is taken care of by initialization */ /* of VALUE to ZERO.) */ if (ib > ia-1) { /* --------------------------------------------- */ $PCHID(ia, ib, value); /* --------------------------------------------- */ } /* THEN ADD ON INTEGRAL OVER (XA,X(IA)). */ if (xa < $x(n=>ia)) { /* Computing MAX */ il = PDLMAX(0,ia - 1); ir = il + 1; /* ------------------------------------- */ $GENERIC() chfie_ans = 0; $CHFIE($x(n=>il), $x(n=>ir), $f(n=>il), $f(n=>ir), $d(n=>il), $d(n=>ir), xa, $x(n=>ia), chfie_ans); value += chfie_ans; /* ------------------------------------- */ } /* THEN ADD ON INTEGRAL OVER (X(IB),XB). */ if (xb > $x(n=>ib)) { /* Computing MIN */ ir = PDLMIN(ib + 1,n-1); il = ir - 1; /* ------------------------------------- */ $GENERIC() chfie_ans = 0; $CHFIE($x(n=>il), $x(n=>ir), $f(n=>il), $f(n=>ir), $d(n=>il), $d(n=>ir), $x(n=>ib), xb, chfie_ans); value += chfie_ans; /* ------------------------------------- */ } /* FINALLY, ADJUST SIGN IF NECESSARY. */ if (a > b) { value = -value; } } } } $ans() = value; EOF ParamDesc => { x => <<'EOF', array of independent variable values. The elements of X must be strictly increasing (error return if not):
X(I-1) .LT. X(I), I = 2(1)N.
EOF
f => <<'EOF',
array of function values. F(I) is the value corresponding to X(I).
EOF
d => <<'EOF',
should contain the derivative values, computed by L</pchip_chim>.
See L</pchip_chid> if the integration limits are data points.
EOF
skip => <<'EOF',
Set to 1 to skip checks on the input data.
This will save time in case these checks have already
been performed (say, in L</pchip_chim> or L</pchip_chic>).
Will be set to TRUE on return with IERR E<gt>= 0.
EOF
la => <<'EOF',
The values of C<$la> and C<$lb> do not have
to lie within C<$x>, although the resulting integral
value will be highly suspect if they are not.
EOF
lb => <<'EOF',
See la
EOF
ierr => <<'EOF',
Error status:0 if successful.
1 if
$lalies outside$x.2 if
$lblies outside$x.3 if both 1 and 2 are true. (Note that this means that either [A,B] contains data interval or the intervals do not intersect at all.)
-1 if
dim($x, 0) < 2-3 if
$xis not strictly increasing.-4 if an error has occurred in a lower-level routine, which should never happen.
Integrate (x,f(x)) over arbitrary limits.
Evaluate the definite integral of a piecewise cubic Hermite function over an arbitrary interval, given by [$la,$lb]. EOF );
pp_def('pchip_chid', Pars => 'x(n); f(n); d(n); indx ia(); indx ib(); [o]ans(); indx [o]ierr(); int [o]skip()', RedoDimsCode => <<'EOF', if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO"); EOF Code => <<'EOF', if (!$skip()) { loop (n=1) %{ if ($x() > $x(n=>n-1)) continue; $ierr() = -1; $CROAK("X-ARRAY NOT STRICTLY INCREASING"); %} } $PCHID($ia(), $ib(), $ans()); EOF GenericTypes => $F, ParamDesc => { x => <<'EOF', array of independent variable values. The elements of X must be strictly increasing:
X(I-1) .LT. X(I), I = 2(1)N.(Error return if not.)
It is a fatal error to pass in data with N < 2. EOF ia => <<'EOF', IA,IB -- (input) indices in X-array for the limits of integration. both must be in the range [0,N-1] (this is different from the Fortran version) - error return if not. No restrictions on their relative values. EOF ib => 'See ia for details', f => 'array of function values. F(I) is the value corresponding to X(I).', skip => <<'EOF', Set to 1 to skip checks on the input data. This will save time in case these checks have already been performed (say, in "pchip_chim" or "pchip_chic"). Will be set to TRUE on return with IERR of 0 or -4. EOF d => <<'EOF', should contain the derivative values, computed by "pchip_chim". EOF ierr => <<'EOF', Error status - this will be set, but an exception will also be thrown:
0 if successful.
-3 if
$xis not strictly increasing.-4 if
$iaor$ibis out of range.
(VALUE will be zero in any of these cases.) NOTE: The above errors are checked in the order listed, and following arguments have NOT been validated. EOF }, Doc => <<'EOF', =for ref
Evaluate the definite integral of a piecewise cubic Hermite function over an interval whose endpoints are data points.
Evaluate the definite integral of a a piecewise cubic Hermite function between x($ia) and x($ib).
See "pchip_chia" for integration between arbitrary limits. EOF );
pp_def('pchip_chbs', Pars => 'x(n); f(n); d(n); sbyte knotyp(); [o]t(nknots=CALC(2*$SIZE(n)+4)); [o]bcoef(ndim=CALC(2*$SIZE(n))); indx [o]ierr()', GenericTypes => $F, Code => pp_line_numbers(__LINE__, <<'EOF'), /* Local variables */ PDL_Indx n = $SIZE(n), ndim = $SIZE(ndim); $ierr() = 0; /* Check argument validity. Set up knot sequence if OK. */ if ($knotyp() > 2) { $ierr() = -1; $CROAK("KNOTYP GREATER THAN 2"); } if ($knotyp() >= 0) { /* Set up knot sequence. */ do { /* inline dpchkt */ /* Set interior knots. */ PDL_Indx j = 0; loop (n) %{ j += 2; $t(nknots=>j+1) = $t(nknots=>j) = $x(); %} /* Assertion: At this point T(3),...,T(NDIM+2) have been set and */ /* J=NDIM+1. */ /* Set end knots according to KNOTYP. */ $GENERIC() hbeg = $x(n=>1) - $x(n=>0); $GENERIC() hend = $x(n=>n-1) - $x(n=>n-2); if ($knotyp() == 1) { /* Extrapolate. */ $t(nknots=>1) = $x(n=>0) - hbeg; $t(nknots=>ndim+2) = $x(n=>n-1) + hend; } else if ($knotyp() == 2) { /* Periodic. */ $t(nknots=>1) = $x(n=>0) - hend; $t(nknots=>ndim+2) = $x(n=>n-1) + hbeg; } else { /* Quadruple end knots. */ $t(nknots=>1) = $x(n=>0); $t(nknots=>ndim+2) = $x(n=>n-1); } $t(nknots=>0) = $t(nknots=>1); $t(nknots=>ndim+3) = $t(nknots=>ndim+2); } while (0); /* end inline dpchkt */ } /* Compute B-spline coefficients. */ $GENERIC() hnew = $t(nknots=>2) - $t(nknots=>0); loop (n) %{ $GENERIC() hold = hnew; /* The following requires mixed mode arithmetic. */ $GENERIC() dov3 = $d() / 3; $bcoef(ndim=>2*n) = $f() - hold * dov3; /* The following assumes T(2*K+1) = X(K). */ hnew = $t(nknots=>2*n+4) - $t(nknots=>2*n+2); $bcoef(ndim=>2*n+1) = $f() + hnew * dov3; %} EOF ParamDesc => { f => <<'EOF', the array of dependent variable values. f(I) is the value corresponding to x(I). EOF d => <<'EOF', the array of derivative values at the data points. d(I) is the value corresponding to x(I). EOF knotyp => <<'EOF', flag which controls the knot sequence. The knot sequence t is normally computed from $x by putting a double knot at each x and setting the end knot pairs according to the value of knotyp (where m = ndim = 2*n):
0 - Quadruple knots at the first and last points.
1 - Replicate lengths of extreme subintervals:
t( 0 ) = t( 1 ) = x(0) - (x(1)-x(0))andt(m+3) = t(m+2) = x(n-1) + (x(n-1)-x(n-2))2 - Periodic placement of boundary knots:
t( 0 ) = t( 1 ) = x(0) - (x(n-1)-x(n-2))andt(m+3) = t(m+2) = x(n) + (x(1)-x(0))<0 - Assume the
nknotsandtwere set in a previous call. This option is provided for improved efficiency when used in a parametric setting.
0 if successful.
-4 if
knotyp > 2. (recoverable)-5 if
knotyp < 0andnknots != 2*n + 4. (recoverable)
Piecewise Cubic Hermite function to B-Spline converter.
Computes the B-spline representation of the PCH function determined by N,X,F,D. The output is the B-representation for the function: NKNOTS, T, BCOEF, NDIM, KORD.
"pchip_chic", "pchip_chim", or "pchip_chsp" can be used to determine an interpolating PCH function from a set of data. The B-spline routine "pchip_bvalu" can be used to evaluate the resulting B-spline representation of the data (i.e. nknots, t, bcoeff, ndim, and kord).
Caution: Since it is assumed that the input PCH function has been computed by one of the other routines in the package PCHIP, input arguments N, X are not checked for validity.
Restrictions/assumptions:
1-
N.GE.2 . (not checked)
2-
X(i).LT.X(i+1), i=1,...,N . (not checked)
4-
KNOTYP.LE.2 . (error return if not)
6-
T(2*k+1) = T(2*k) = X(k), k=1,...,N . (not checked)
* Indicates this applies only if KNOTYP.LT.0 .
References: F. N. Fritsch, "Representations for parametric cubic splines," Computer Aided Geometric Design 6 (1989), pp.79-82. EOF );
pp_def('pchip_bvalu', Pars => 't(nplusk); a(n); indx ideriv(); x(); [o]ans(); indx [o] inbv(); [t] work(k3=CALC(3*($SIZE(nplusk)-$SIZE(n))));', GenericTypes => $F, RedoDimsCode => <<'EOF', PDL_Indx k = $SIZE(nplusk) - $SIZE(n); if (k < 1) $CROAK("K DOES NOT SATISFY K.GE.1"); if ($SIZE(n) < k) $CROAK("N DOES NOT SATISFY N.GE.K"); EOF Code => pp_line_numbers(__LINE__, <<'EOF'), PDL_Indx k = $SIZE(nplusk) - $SIZE(n); if ($ideriv() < 0 || $ideriv() >= k) $CROAK("IDERIV DOES NOT SATISFY 0.LE.IDERIV.LT.K"); PDL_Indx i; int mflag; /* *** FIND *I* IN (K,N) SUCH THAT T(I) .LE. X .LT. T(I+1) */ /* (OR, .LE. T(I+1) IF T(I) .LT. T(I+1) = T(N+1)). */ do { /* inlined dintrv */ PDL_Indx ihi = $inbv() + 1, lxt = $SIZE(n); if (ihi >= lxt) { if ($x() >= $t(nplusk=>lxt)) { mflag = 1; i = lxt; break; } if (lxt <= 0) { mflag = -1; i = 0; break; } ihi = $inbv() = lxt; } char skipflag = 0; if ($x() < $t(nplusk=>ihi)) { PDL_Indx inbv = $inbv(); if ($x() >= $t(nplusk=>inbv)) { mflag = 0; i = $inbv(); break; } /* *** NOW X .LT. XT(IHI) . FIND LOWER BOUND */ PDL_Indx istep = 1; while (1) { ihi = $inbv(); $inbv() = ihi - istep; if ($inbv() <= 0) { break; } PDL_Indx inbv = $inbv(); if ($x() >= $t(nplusk=>inbv)) { skipflag = 1; break; } istep <<= 1; } if (!skipflag) { $inbv() = 0; if ($x() < $t(nplusk=>0)) { mflag = -1; i = 0; break; } } skipflag = 1; /* *** NOW X .GE. XT(ILO) . FIND UPPER BOUND */ } if (!skipflag) { PDL_Indx istep = 1; while (1) { $inbv() = ihi; ihi = $inbv() + istep; if (ihi >= lxt) break; if ($x() < $t(nplusk=>ihi)) { skipflag = 1; break; } istep <<= 1; } if (!skipflag) { if ($x() >= $t(nplusk=>lxt)) { mflag = 1; i = lxt; break; } ihi = lxt; } } /* *** NOW XT(ILO) .LE. X .LT. XT(IHI) . NARROW THE INTERVAL */ while (1) { PDL_Indx middle = ($inbv() + ihi) / 2; if (middle == $inbv()) { mflag = 0; i = $inbv(); break; } /* NOTE. IT IS ASSUMED THAT MIDDLE = ILO IN CASE IHI = ILO+1 */ if ($x() < $t(nplusk=>middle)) ihi = middle; else $inbv() = middle; } } while (0); /* end dintrv inlined */ if ($x() < $t(nplusk=>k-1)) { $CROAK("X IS N0T GREATER THAN OR EQUAL TO T(K)"); } if (mflag != 0) { if ($x() > $t(nplusk=>i)) { $CROAK("X IS NOT LESS THAN OR EQUAL TO T(N+1)"); } while (1) { if (i == k-1) { $CROAK("A LEFT LIMITING VALUE CANNOT BE OBTAINED AT T(K)"); } --i; if ($x() != $t(nplusk=>i)) { break; } } /* *** DIFFERENCE THE COEFFICIENTS *IDERIV* TIMES */ /* WORK(I) = AJ(I), WORK(K+I) = DP(I), WORK(K+K+I) = DM(I), I=1.K */ } PDL_Indx imk = i+1 - k, j; loop (k3=:k) %{ $work() = $a(n=>imk+k3); %} if ($ideriv() != 0) { for (j = 0; j < $ideriv(); ++j) { PDL_Indx kmj = k - j - 1; $GENERIC() fkmj = kmj; loop (k3=0:kmj) %{ PDL_Indx ihi = i+1 + k3; $work() = ($work(k3=>k3+1) - $work()) / ($t(nplusk=>ihi) - $t(nplusk=>ihi-kmj)) * fkmj; %} } /* *** COMPUTE VALUE AT *X* IN (T(I),T(I+1)) OF IDERIV-TH DERIVATIVE, */ /* GIVEN ITS RELEVANT B-SPLINE COEFF. IN AJ(1),...,AJ(K-IDERIV). */ } PDL_Indx km1 = k - 1; if ($ideriv() != km1) { PDL_Indx j, j1 = k, kpk = k + k, j2 = kpk, kmider = k - $ideriv(); for (j = 0; j < kmider; ++j) { PDL_Indx ipj = i + j + 1; $work(k3=>j1) = $t(nplusk=>ipj) - $x(); $work(k3=>j2) = $x() - $t(nplusk=>i-j); ++j1; ++j2; } for (j = $ideriv(); j < km1; ++j) { PDL_Indx kmj = k - j - 1, ilo = kpk + kmj - 1; loop (k3=0:kmj) %{ $work() = ($work(k3=>k3+1) * $work(k3=>ilo) + $work() * $work(k3=>k+k3)) / ($work(k3=>ilo) + $work(k3=>k+k3)); --ilo; %} } } $ans() = $work(k3=>0); EOF ParamDesc => { t => <<'EOF', knot vector of length N+K EOF a => <<'EOF', B-spline coefficient vector of length N, the number of B-spline coefficients; N = sum of knot multiplicities-K EOF ideriv => <<'EOF', order of the derivative, 0 .LE. IDERIV .LE. K-1
IDERIV=0 returns the B-spline value EOF x => <<'EOF', T(K) .LE. X .LE. T(N+1) EOF inbv => <<'EOF', contains information for efficient processing after the initial call and INBV must not be changed by the user. Distinct splines require distinct INBV parameters. EOF ans => <<'EOF', value of the IDERIV-th derivative at X EOF }, Doc => <<'EOF', =for ref
Evaluate the B-representation of a B-spline at X for the function value or any of its derivatives.
Evaluates the B-representation (T,A,N,K) of a B-spline at X for the function value on IDERIV = 0 or any of its derivatives on IDERIV = 1,2,...,K-1. Right limiting values (right derivatives) are returned except at the right end point X=T(N+1) where left limiting values are computed. The spline is defined on T(K) .LE. X .LE. T(N+1). BVALU returns a fatal error message when X is outside of this interval.
To compute left derivatives or left limiting values at a knot T(I), replace N by I-1 and set X=T(I), I=K+1,N+1.
References: Carl de Boor, Package for calculating with B-splines, SIAM Journal on Numerical Analysis 14, 3 (June 1977), pp. 441-472. EOF );
pp_addpm({At=>'Bot'},<<'EOD');
AUTHOR
Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu). Contributions by Christian Soeller (c.soeller@auckland.ac.nz), Karl Glazebrook (kgb@aaoepp.aao.gov.au), Craig DeForest (deforest@boulder.swri.edu) and Jarle Brinchmann (jarle@astro.up.pt) All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.
Updated for CPAN viewing compatibility by David Mertens.
8 POD Errors
The following errors were encountered while parsing the POD:
- Around line 5073:
=back doesn't take any parameters, but you said =back EOF vc => 'See ic for details', mflag => <<'EOF', Set to non-zero to use a formula based on the 3-point difference formula at switch points. If C<$mflag E<gt> 0>, then the interpolant at switch points is forced to not deviate from the data by more than C<$mflag*dfloc>, where C<dfloc> is the maximum of the change of C<$f> on this interval and its two immediate neighbours. If C<$mflag E<lt> 0>, no such control is to be imposed. EOF x => <<'EOF', array of independent variable values. The elements of X must be strictly increasing:
- Around line 5468:
=back doesn't take any parameters, but you said =back EOF }, Doc => <<'EOF', =for ref
- Around line 5526:
=back doesn't take any parameters, but you said =back EOF fe => <<'EOF', array of values of the cubic Hermite function defined by N, X, F, D at the points XE. EOF de => <<'EOF', array of values of the first derivative of the same function at the points XE. EOF ierr => <<'EOF', Error status:
- Around line 5566:
=back doesn't take any parameters, but you said =back EOF }, Doc => <<'EOF', =for ref
- Around line 5633:
=back doesn't take any parameters, but you said =back EOF fe => <<'EOF', array of values of the cubic Hermite function defined by N, X, F, D at the points XE. EOF ierr => <<'EOF', Error status returned by C<$>:
- Around line 5858:
=back doesn't take any parameters, but you said =back EOF }, Doc => <<'EOF', =for ref
- Around line 6052:
=back doesn't take any parameters, but you said =back EOF t => <<'EOF', the array of C<2*n+4> knots for the B-representation and may be changed by the routine. If C<knotyp E<gt>= 0>, C<t> will be changed so that the interior double knots are equal to the x-values and the boundary knots set as indicated above, otherwise it is assumed that C<t> was set by a previous call (no check is made to verify that the data forms a legitimate knot sequence). EOF bcoef => 'the array of 2*N B-spline coefficients.', ierr => <<'EOF', Error status:
- Around line 6082:
=back doesn't take any parameters, but you said =back EOF }, Doc => <<'EOF', =for ref