lib/PDL/Primitive.pd

filter: Statementstmt 98.8% 86 / 87 Branchbran 72.5% 135 / 186 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 80.9% 221 / 273 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« lib/PDL/Core/pdlaffine.c ↑ Summary lib/PDL/ImageND-pp-contour_segments.c »
1 use strict;
2 use warnings;
3 use PDL::Types qw(ppdefs_all types);
4 my $F = [map $_->ppsym, grep $_->real && !$_->integer, types()];
5 my $AF = [map $_->ppsym, grep !$_->integer, types];
6 $AF = [(grep $_ ne 'D', @$AF), 'D']; # so defaults to D if non-float given
7  
8 { no warnings 'once'; # pass info back to Makefile.PL
9 $PDL::Core::Dev::EXTRAS{$::PDLMOD}{OBJECT} .= " $::PDLBASE-xoshiro256plus\$(OBJ_EXT)";
10 }
11  
12 pp_addpm({At=>'Top'},<<'EOD');
13 use strict;
14 use warnings;
15 use PDL::Slices;
16 use Carp;
17  
18 =head1 NAME
19  
20 PDL::Primitive - primitive operations for pdl
21  
22 =head1 DESCRIPTION
23  
24 This module provides some primitive and useful functions defined
25 using PDL::PP and able to use the new indexing tricks.
26  
27 See L<PDL::Indexing> for how to use indices creatively.
28 For explanation of the signature format, see L<PDL::PP>.
29  
30 =head1 SYNOPSIS
31  
32 # Pulls in PDL::Primitive, among other modules.
33 use PDL;
34  
35 # Only pull in PDL::Primitive:
36 use PDL::Primitive;
37  
38 =cut
39  
40 EOD
41  
42 ################################################################
43 # a whole bunch of quite basic functions for inner, outer
44 # and matrix products (operations that are not normally
45 # available via operator overloading)
46 ################################################################
47  
48 pp_def('inner',
49 HandleBad => 1,
50 Pars => 'a(n); b(n); [o]c();',
51 GenericTypes => [ppdefs_all],
52 Code => <<'EOF',
53 complex long double tmp = 0;
54 PDL_IF_BAD(int badflag = 0;,)
55 loop(n) %{
56 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b())) { badflag = 1; break; }
57 else,) { tmp += $a() * $b(); }
58 %}
59 PDL_IF_BAD(if (badflag) { $SETBAD(c()); $PDLSTATESETBAD(c); }
60 else,) { $c() = tmp; }
61 EOF
62 Doc => '
63 =for ref
64  
65 Inner product over one dimension
66  
67 c = sum_i a_i * b_i
68  
69 See also L</norm>, L<PDL::Ufunc/magnover>.
70 ',
71 BadDoc => '
72 If C<a() * b()> contains only bad data,
73 C<c()> is set bad. Otherwise C<c()> will have its bad flag cleared,
74 as it will not contain any bad values.
75 ',
76 ); # pp_def( inner )
77  
78 pp_def('outer',
79 HandleBad => 1,
80 Pars => 'a(n); b(m); [o]c(n,m);',
81 GenericTypes => [ppdefs_all],
82 Code => <<'EOF',
83 loop(n,m) %{
84 PDL_IF_BAD(if ( $ISBAD(a()) || $ISBAD(b()) ) { $SETBAD(c()); continue; },)
85 $c() = $a() * $b();
86 %}
87 EOF
88 Doc => '
89 =for ref
90  
91 outer product over one dimension
92  
93 Naturally, it is possible to achieve the effects of outer
94 product simply by broadcasting over the "C<*>"
95 operator but this function is provided for convenience.
96 '); # pp_def( outer )
97  
98 pp_addpm(<<'EOD');
99 =head2 x
100  
101 =for sig
102  
103 Signature: (a(i,z), b(x,i),[o]c(x,z))
104  
105 =for ref
106  
107 Matrix multiplication
108  
109 PDL overloads the C<x> operator (normally the repeat operator) for
110 matrix multiplication. The number of columns (size of the 0
111 dimension) in the left-hand argument must normally equal the number of
112 rows (size of the 1 dimension) in the right-hand argument.
113  
114 Row vectors are represented as (N x 1) two-dimensional PDLs, or you
115 may be sloppy and use a one-dimensional PDL. Column vectors are
116 represented as (1 x N) two-dimensional PDLs.
117  
118 Broadcasting occurs in the usual way, but as both the 0 and 1 dimension
119 (if present) are included in the operation, you must be sure that
120 you don't try to broadcast over either of those dims.
121  
122 Of note, due to how Perl v5.14.0 and above implement operator overloading of
123 the C<x> operator, the use of parentheses for the left operand creates a list
124 context, that is
125  
126 pdl> ( $x * $y ) x $z
127 ERROR: Argument "..." isn't numeric in repeat (x) ...
128  
129 treats C<$z> as a numeric count for the list repeat operation and does not call
130 the scalar form of the overloaded operator. To use the operator in this case,
131 use a scalar context:
132  
133 pdl> scalar( $x * $y ) x $z
134  
135 or by calling L</matmult> directly:
136  
137 pdl> ( $x * $y )->matmult( $z )
138  
139 EXAMPLES
140  
141 Here are some simple ways to define vectors and matrices:
142  
143 pdl> $r = pdl(1,2); # A row vector
144 pdl> $c = pdl([[3],[4]]); # A column vector
145 pdl> $c = pdl(3,4)->(*1); # A column vector, using NiceSlice
146 pdl> $m = pdl([[1,2],[3,4]]); # A 2x2 matrix
147  
148 Now that we have a few objects prepared, here is how to
149 matrix-multiply them:
150  
151 pdl> print $r x $m # row x matrix = row
152 [
153 [ 7 10]
154 ]
155  
156 pdl> print $m x $r # matrix x row = ERROR
157 PDL: Dim mismatch in matmult of [2x2] x [2x1]: 2 != 1
158  
159 pdl> print $m x $c # matrix x column = column
160 [
161 [ 5]
162 [11]
163 ]
164  
165 pdl> print $m x 2 # Trivial case: scalar mult.
166 [
167 [2 4]
168 [6 8]
169 ]
170  
171 pdl> print $r x $c # row x column = scalar
172 [
173 [11]
174 ]
175  
176 pdl> print $c x $r # column x row = matrix
177 [
178 [3 6]
179 [4 8]
180 ]
181  
182 INTERNALS
183  
184 The mechanics of the multiplication are carried out by the
185 L</matmult> method.
186  
187 =cut
188  
189 EOD
190  
191 pp_def('matmult',
192 HandleBad=>1,
193 Pars => 'a(t,h); b(w,t); [o]c(w,h);',
194 GenericTypes => [ppdefs_all],
195 Overload => 'x',
196 PMCode => pp_line_numbers(__LINE__, <<'EOPM'),
197 sub PDL::matmult {
198 my ($x,$y,$c) = @_;
199 $y = PDL->topdl($y);
200 $c = PDL->null if !UNIVERSAL::isa($c, 'PDL');
201 while($x->getndims < 2) {$x = $x->dummy(-1)}
202 while($y->getndims < 2) {$y = $y->dummy(-1)}
203 return ($c .= $x * $y) if( ($x->dim(0)==1 && $x->dim(1)==1) ||
204 ($y->dim(0)==1 && $y->dim(1)==1) );
205 barf sprintf 'Dim mismatch in matmult of [%1$dx%2$d] x [%3$dx%4$d]: %1$d != %4$d',$x->dim(0),$x->dim(1),$y->dim(0),$y->dim(1)
206 if $y->dim(1) != $x->dim(0);
207 PDL::_matmult_int($x,$y,$c);
208 $c;
209 }
210 EOPM
211 Code => <<'EOC',
212 PDL_Indx tsiz = 8 * sizeof(double) / sizeof($GENERIC());
213  
214 // Cache the dimincs to avoid constant lookups
215 PDL_Indx atdi = PDL_REPRINCS($PDL(a))[0];
216 PDL_Indx btdi = PDL_REPRINCS($PDL(b))[1];
217  
218 broadcastloop %{
219 // Loop over tiles
220 loop (h=::tsiz,w=::tsiz) %{
221 PDL_Indx h_outer = h, w_outer = w;
222 // Zero the output for this tile
223 loop (h=h_outer:h_outer+tsiz,w=w_outer:w_outer+tsiz) %{ $c() = 0; %}
224 loop (t=::tsiz,h=h_outer:h_outer+tsiz,w=w_outer:w_outer+tsiz) %{
225 // Cache the accumulated value for the output
226 $GENERIC() cc = $c();
227 PDL_IF_BAD(if ($ISBADVAR(cc,c)) continue;,)
228 // Cache data pointers before 't' run through tile
229 $GENERIC() *ad = &($a());
230 $GENERIC() *bd = &($b());
231 // Hotspot - run the 't' summation
232 PDL_Indx t_outer = t;
233 PDL_IF_BAD(char c_isbad = 0;,)
234 loop (t=t_outer:t_outer+tsiz) %{
235 PDL_IF_BAD(if ($ISBADVAR(*ad,a) || $ISBADVAR(*bd,b)) { c_isbad = 1; break; },)
236 cc += *ad * *bd;
237 ad += atdi;
238 bd += btdi;
239 %}
240 // put the output back to be further accumulated later
241 PDL_IF_BAD(if (c_isbad) { $SETBAD(c()); continue; },)
242 $c() = cc;
243 %}
244 %}
245 %}
246 EOC
247 Doc => <<'EOD'
248 =for ref
249  
250 Matrix multiplication
251  
252 Notionally, matrix multiplication $x x $y is equivalent to the
253 broadcasting expression
254  
255 $x->dummy(1)->inner($y->xchg(0,1)->dummy(2),$c);
256  
257 but for large matrices that breaks CPU cache and is slow. Instead,
258 matmult calculates its result in 32x32x32 tiles, to keep the memory
259 footprint within cache as long as possible on most modern CPUs.
260  
261 For usage, see L</x>, a description of the overloaded 'x' operator
262  
263 EOD
264 );
265  
266 pp_def('innerwt',
267 HandleBad => 1,
268 Pars => 'a(n); b(n); c(n); [o]d();',
269 GenericTypes => [ppdefs_all],
270 Code => <<'EOF',
271 complex long double tmp = 0;
272 PDL_IF_BAD(int flag = 0;,)
273 loop(n) %{
274 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,)
275 tmp += $a() * $b() * $c();
276 %}
277 PDL_IF_BAD(if (!flag) { $SETBAD(d()); }
278 else,) { $d() = tmp; }
279 EOF
280 Doc => '
281  
282 =for ref
283  
284 Weighted (i.e. triple) inner product
285  
286 d = sum_i a(i) b(i) c(i)
287 '
288 );
289  
290 pp_def('inner2',
291 HandleBad => 1,
292 Pars => 'a(n); b(n,m); c(m); [o]d();',
293 GenericTypes => [ppdefs_all],
294 Code => <<'EOF',
295 complex long double tmp = 0;
296 PDL_IF_BAD(int flag = 0;,)
297 loop(n,m) %{
298 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,)
299 tmp += $a() * $b() * $c();
300 %}
301 PDL_IF_BAD(if (!flag) { $SETBAD(d()); }
302 else,) { $d() = tmp; }
303 EOF
304 Doc => '
305 =for ref
306  
307 Inner product of two vectors and a matrix
308  
309 d = sum_ij a(i) b(i,j) c(j)
310  
311 Note that you should probably not broadcast over C<a> and C<c> since that would be
312 very wasteful. Instead, you should use a temporary for C<b*c>.
313 '
314 );
315  
316 pp_def('inner2d',
317 HandleBad => 1,
318 Pars => 'a(n,m); b(n,m); [o]c();',
319 GenericTypes => [ppdefs_all],
320 Code => <<'EOF',
321 complex long double tmp = 0;
322 PDL_IF_BAD(int flag = 0;,)
323 loop(n,m) %{
324 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b())) continue;flag = 1;,)
325 tmp += $a() * $b();
326 %}
327 PDL_IF_BAD(if (!flag) { $SETBAD(c()); }
328 else,) { $c() = tmp; }
329 EOF
330 Doc => '
331 =for ref
332  
333 Inner product over 2 dimensions.
334  
335 Equivalent to
336  
337 $c = inner($x->clump(2), $y->clump(2))
338 '
339 );
340  
341 pp_def('inner2t',
342 HandleBad => 1,
343 Pars => 'a(j,n); b(n,m); c(m,k); [t]tmp(n,k); [o]d(j,k);',
344 GenericTypes => [ppdefs_all],
345 Code => <<'EOF',
346 loop(n,k) %{
347 complex long double tmp0 = 0;
348 PDL_IF_BAD(int flag = 0;,)
349 loop(m) %{
350 PDL_IF_BAD(if ($ISBAD(b()) || $ISBAD(c())) continue;flag = 1;,)
351 tmp0 += $b() * $c();
352 %}
353 PDL_IF_BAD(if (!flag) { $SETBAD(tmp()); }
354 else,) { $tmp() = tmp0; }
355 %}
356 loop(j,k) %{
357 complex long double tmp1 = 0;
358 PDL_IF_BAD(int flag = 0;,)
359 loop(n) %{
360 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(tmp())) continue;flag = 1;,)
361 tmp1 += $a() * $tmp();
362 %}
363 PDL_IF_BAD(if (!flag) { $SETBAD(d()); }
364 else,) { $d() = tmp1; }
365 %}
366 EOF
367 Doc => '
368 =for ref
369  
370 Efficient Triple matrix product C<a*b*c>
371  
372 Efficiency comes from by using the temporary C<tmp>. This operation only
373 scales as C<N**3> whereas broadcasting using L</inner2> would scale
374 as C<N**4>.
375  
376 The reason for having this routine is that you do not need to
377 have the same broadcast-dimensions for C<tmp> as for the other arguments,
378 which in case of large numbers of matrices makes this much more
379 memory-efficient.
380  
381 It is hoped that things like this could be taken care of as a kind of
382 closure at some point.
383 '
384 ); # pp_def inner2t()
385  
386 # a helper function for the cross product definition
387 sub crassgn {
388 "\$c(tri => $_[0]) = \$a(tri => $_[1])*\$b(tri => $_[2]) -
389 \$a(tri => $_[2])*\$b(tri => $_[1]);"
390 }
391  
392 pp_def('crossp',
393 Doc => <<'EOD',
394 =for ref
395  
396 Cross product of two 3D vectors
397  
398 After
399  
400 =for example
401  
402 $c = crossp $x, $y
403  
404 the inner product C<$c*$x> and C<$c*$y> will be zero, i.e. C<$c> is
405 orthogonal to C<$x> and C<$y>
406 EOD
407 Pars => 'a(tri=3); b(tri); [o] c(tri)',
408 GenericTypes => [ppdefs_all],
409 Code =>
410 crassgn(0,1,2)."\n".
411 crassgn(1,2,0)."\n".
412 crassgn(2,0,1),
413 );
414  
415 pp_def('norm',
416 HandleBad => 1,
417 Inplace => 1,
418 Pars => 'vec(n); [o] norm(n)',
419 GenericTypes => [ppdefs_all],
420 Doc => 'Normalises a vector to unit Euclidean length
421  
422 See also L</inner>, L<PDL::Ufunc/magnover>.
423 ',
424 Code => <<'EOF',
425 long double sum=0;
426 PDL_IF_BAD(int flag = 0;,)
427 loop(n) %{
428 PDL_IF_BAD(if ($ISBAD(vec())) continue; flag = 1;,)
429 sum += PDL_IF_GENTYPE_REAL(
430 $vec()*$vec(),
431 creall($vec())*creall($vec()) + cimagl($vec())*cimagl($vec())
432 );
433 %}
434 PDL_IF_BAD(if ( !flag ) {
435 loop(n) %{ $SETBAD(norm()); %}
436 continue;
437 },)
438 if (sum > 0) {
439 sum = sqrtl(sum);
440 loop(n) %{
441 PDL_IF_BAD(if ( $ISBAD(vec()) ) { $SETBAD(norm()); }
442 else ,) { $norm() = $vec()/sum; }
443 %}
444 } else {
445 loop(n) %{
446 PDL_IF_BAD(if ( $ISBAD(vec()) ) { $SETBAD(norm()); }
447 else ,) { $norm() = $vec(); }
448 %}
449 }
450 EOF
451 );
452  
453 # this one was motivated by the need to compute
454 # the circular mean efficiently
455 # without it could not be done efficiently or without
456 # creating large intermediates (check pdl-porters for
457 # discussion)
458 # see PDL::ImageND for info about the circ_mean function
459  
460 pp_def(
461 'indadd',
462 HandleBad => 1,
463 Pars => 'input(n); indx ind(n); [io] sum(m)',
464 GenericTypes => [ppdefs_all],
465 Code => <<'EOF',
466 loop(n) %{
467 register PDL_Indx this_ind = $ind();
468 PDL_IF_BAD(
469 if ($ISBADVAR(this_ind,ind)) $CROAK("bad index %"IND_FLAG, n);
470 if ($ISBAD(input())) { $SETBAD(sum(m => this_ind)); continue; },)
471 if (this_ind<0 || this_ind>=$SIZE(m))
472 $CROAK("invalid index %"IND_FLAG"; range 0..%"IND_FLAG, this_ind, $SIZE(m));
473 $sum(m => this_ind) += $input();
474 %}
475 EOF
476 BadDoc => 'The routine barfs on bad indices, and bad inputs set target outputs bad.',
477 Doc=>'
478 =for ref
479  
480 Broadcasting index add: add C<input> to the C<ind> element of C<sum>, i.e:
481  
482 sum(ind) += input
483  
484 =for example
485  
486 Simple example:
487  
488 $x = 2;
489 $ind = 3;
490 $sum = zeroes(10);
491 indadd($x,$ind, $sum);
492 print $sum
493 #Result: ( 2 added to element 3 of $sum)
494 # [0 0 0 2 0 0 0 0 0 0]
495  
496 Broadcasting example:
497  
498 $x = pdl( 1,2,3);
499 $ind = pdl( 1,4,6);
500 $sum = zeroes(10);
501 indadd($x,$ind, $sum);
502 print $sum."\n";
503 #Result: ( 1, 2, and 3 added to elements 1,4,6 $sum)
504 # [0 1 0 0 2 0 3 0 0 0]
505  
506 =cut
507 ');
508  
509 # 1D convolution
510 # useful for broadcasted 1D filters
511 pp_def('conv1d',
512 Doc => << 'EOD',
513  
514 =for ref
515  
516 1D convolution along first dimension
517  
518 The m-th element of the discrete convolution of an input ndarray
519 C<$a> of size C<$M>, and a kernel ndarray C<$kern> of size C<$P>, is
520 calculated as
521  
522 n = ($P-1)/2
523 ====
524 \
525 ($a conv1d $kern)[m] = > $a_ext[m - n] * $kern[n]
526 /
527 ====
528 n = -($P-1)/2
529  
530 where C<$a_ext> is either the periodic (or reflected) extension of
531 C<$a> so it is equal to C<$a> on C< 0..$M-1 > and equal to the
532 corresponding periodic/reflected image of C<$a> outside that range.
533  
534  
535 =for example
536  
537 $con = conv1d sequence(10), pdl(-1,0,1);
538  
539 $con = conv1d sequence(10), pdl(-1,0,1), {Boundary => 'reflect'};
540  
541 By default, periodic boundary conditions are assumed (i.e. wrap around).
542 Alternatively, you can request reflective boundary conditions using
543 the C<Boundary> option:
544  
545 {Boundary => 'reflect'} # case in 'reflect' doesn't matter
546  
547 The convolution is performed along the first dimension. To apply it across
548 another dimension use the slicing routines, e.g.
549  
550 $y = $x->mv(2,0)->conv1d($kernel)->mv(0,2); # along third dim
551  
552 This function is useful for broadcasted filtering of 1D signals.
553  
554 Compare also L<conv2d|PDL::Image2D/conv2d>, L<convolve|PDL::ImageND/convolve>,
555 L<fftconvolve|PDL::FFT/fftconvolve()>
556  
557 =for bad
558  
559 WARNING: C<conv1d> processes bad values in its inputs as
560 the numeric value of C<< $pdl->badvalue >> so it is not
561 recommended for processing pdls with bad values in them
562 unless special care is taken.
563 EOD
564 Pars => 'a(m); kern(p); [o]b(m);',
565 GenericTypes => [ppdefs_all],
566 OtherPars => 'int reflect;',
567 HandleBad => 0,
568 PMCode => pp_line_numbers(__LINE__, <<'EOPM'),
569 sub PDL::conv1d {
570 my $opt = pop @_ if ref($_[-1]) eq 'HASH';
571 die 'Usage: conv1d( a(m), kern(p), [o]b(m), {Options} )'
572 if @_<2 || @_>3;
573 my($x,$kern) = @_;
574 my $c = @_ == 3 ? $_[2] : PDL->null;
575 PDL::_conv1d_int($x,$kern,$c,
576 !(defined $opt && exists $$opt{Boundary}) ? 0 :
577 lc $$opt{Boundary} eq "reflect");
578 return $c;
579 }
580 EOPM
581 CHeader => '
582 /* Fast Modulus with proper negative behaviour */
583 #define REALMOD(a,b) while ((a)>=(b)) (a) -= (b); while ((a)<0) (a) += (b);
584 ',
585 Code => '
586 int reflect = $COMP(reflect);
587 PDL_Indx m_size = $SIZE(m), p_size = $SIZE(p);
588 PDL_Indx poff = (p_size-1)/2;
589 loop(m) %{
590 complex long double tmp = 0;
591 loop(p) %{
592 PDL_Indx pflip = p_size - 1 - p, i2 = m+p - poff;
593 if (reflect && i2<0)
594 i2 = -i2;
595 if (reflect && i2>=m_size)
596 i2 = m_size-(i2-m_size+1);
597 REALMOD(i2,m_size);
598 tmp += $a(m=>i2) * $kern(p=>pflip);
599 %}
600 $b() = tmp;
601 %}
602 ');
603  
604  
605 # this can be achieved by
606 # ($x->dummy(0) == $y)->orover
607 # but this one avoids a larger intermediate and potentially shortcuts
608 pp_def('in',
609 Pars => 'a(); b(n); [o] c()',
610 GenericTypes => [ppdefs_all],
611 Code => '$c() = 0;
612 loop(n) %{ if ($a() == $b()) {$c() = 1; break;} %}',
613 Doc => <<'EOD',
614  
615 =for ref
616  
617 test if a is in the set of values b
618  
619 =for example
620  
621 $goodmsk = $labels->in($goodlabels);
622 print pdl(3,1,4,6,2)->in(pdl(2,3,3));
623 [1 0 0 0 1]
624  
625 C<in> is akin to the I<is an element of> of set theory. In principle,
626 PDL broadcasting could be used to achieve its functionality by using a
627 construct like
628  
629 $msk = ($labels->dummy(0) == $goodlabels)->orover;
630  
631 However, C<in> doesn't create a (potentially large) intermediate
632 and is generally faster.
633 EOD
634 );
635  
636 pp_add_exported ('', 'uniq');
637 pp_addpm (<< 'EOPM');
638 =head2 uniq
639  
640 =for ref
641  
642 return all unique elements of an ndarray
643  
644 The unique elements are returned in ascending order.
645  
646 =for example
647  
648 PDL> p pdl(2,2,2,4,0,-1,6,6)->uniq
649 [-1 0 2 4 6] # 0 is returned 2nd (sorted order)
650  
651 PDL> p pdl(2,2,2,4,nan,-1,6,6)->uniq
652 [-1 2 4 6 nan] # NaN value is returned at end
653  
654 Note: The returned pdl is 1D; any structure of the input
655 ndarray is lost. C<NaN> values are never compare equal to
656 any other values, even themselves. As a result, they are
657 always unique. C<uniq> returns the NaN values at the end
658 of the result ndarray. This follows the Matlab usage.
659  
660 See L</uniqind> if you need the indices of the unique
661 elements rather than the values.
662  
663 =for bad
664  
665 Bad values are not considered unique by uniq and are ignored.
666  
667 $x=sequence(10);
668 $x=$x->setbadif($x%3);
669 print $x->uniq;
670 [0 3 6 9]
671  
672 =cut
673  
674 *uniq = \&PDL::uniq;
675 # return unique elements of array
676 # find as jumps in the sorted array
677 # flattens in the process
678 sub PDL::uniq {
679 my ($arr) = @_;
680 return $arr if($arr->nelem == 0); # The null list is unique (CED)
681 return $arr->flat if($arr->nelem == 1); # singleton list is unique
682 my $aflat = $arr->flat;
683 my $srt = $aflat->where($aflat==$aflat)->qsort; # no NaNs or BADs for qsort
684 my $nans = $aflat->where($aflat!=$aflat);
685 my $uniq = ($srt->nelem > 1) ? $srt->where($srt != $srt->rotate(-1)) : $srt;
686 # make sure we return something if there is only one value
687 (
688 $uniq->nelem > 0 ? $uniq :
689 $srt->nelem == 0 ? $srt :
690 PDL::pdl( ref($srt), [$srt->index(0)] )
691 )->append($nans);
692 }
693 EOPM
694  
695 pp_add_exported ('', 'uniqind');
696 pp_addpm (<< 'EOPM');
697 =head2 uniqind
698  
699 =for ref
700  
701 Return the indices of all unique elements of an ndarray
702 The order is in the order of the values to be consistent
703 with uniq. C<NaN> values never compare equal with any
704 other value and so are always unique. This follows the
705 Matlab usage.
706  
707 =for example
708  
709 PDL> p pdl(2,2,2,4,0,-1,6,6)->uniqind
710 [5 4 1 3 6] # the 0 at index 4 is returned 2nd, but...
711  
712 PDL> p pdl(2,2,2,4,nan,-1,6,6)->uniqind
713 [5 1 3 6 4] # ...the NaN at index 4 is returned at end
714  
715  
716 Note: The returned pdl is 1D; any structure of the input
717 ndarray is lost.
718  
719 See L</uniq> if you want the unique values instead of the
720 indices.
721  
722 =for bad
723  
724 Bad values are not considered unique by uniqind and are ignored.
725  
726 =cut
727  
728 *uniqind = \&PDL::uniqind;
729 # return unique elements of array
730 # find as jumps in the sorted array
731 # flattens in the process
732 sub PDL::uniqind {
733 use PDL::Core 'barf';
734 my ($arr) = @_;
735 return $arr if($arr->nelem == 0); # The null list is unique (CED)
736 # Different from uniq we sort and store the result in an intermediary
737 my $aflat = $arr->flat;
738 my $nanind = which($aflat!=$aflat); # NaN indexes
739 my $good = PDL->sequence(indx, $aflat->dims)->where($aflat==$aflat); # good indexes
740 my $i_srt = $aflat->where($aflat==$aflat)->qsorti; # no BAD or NaN values for qsorti
741 my $srt = $aflat->where($aflat==$aflat)->index($i_srt);
742 my $uniqind;
743 if ($srt->nelem > 0) {
744 $uniqind = which($srt != $srt->rotate(-1));
745 $uniqind = $i_srt->slice('0') if $uniqind->isempty;
746 } else {
747 $uniqind = which($srt);
748 }
749 # Now map back to the original space
750 my $ansind = $nanind;
751 if ( $uniqind->nelem > 0 ) {
752 $ansind = ($good->index($i_srt->index($uniqind)))->append($ansind);
753 } else {
754 $ansind = $uniqind->append($ansind);
755 }
756 return $ansind;
757 }
758  
759 EOPM
760  
761 pp_add_exported ('', 'uniqvec');
762 pp_addpm (<< 'EOPM');
763 =head2 uniqvec
764  
765 =for ref
766  
767 Return all unique vectors out of a collection
768  
769 NOTE: If any vectors in the input ndarray have NaN values
770 they are returned at the end of the non-NaN ones. This is
771 because, by definition, NaN values never compare equal with
772 any other value.
773  
774 NOTE: The current implementation does not sort the vectors
775 containing NaN values.
776  
777 The unique vectors are returned in lexicographically sorted
778 ascending order. The 0th dimension of the input PDL is treated
779 as a dimensional index within each vector, and the 1st and any
780 higher dimensions are taken to run across vectors. The return
781 value is always 2D; any structure of the input PDL (beyond using
782 the 0th dimension for vector index) is lost.
783  
784 See also L</uniq> for a unique list of scalars; and
785 L<qsortvec|PDL::Ufunc/qsortvec> for sorting a list of vectors
786 lexicographcally.
787  
788 =for bad
789  
790 If a vector contains all bad values, it is ignored as in L</uniq>.
791 If some of the values are good, it is treated as a normal vector. For
792 example, [1 2 BAD] and [BAD 2 3] could be returned, but [BAD BAD BAD]
793 could not. Vectors containing BAD values will be returned after any
794 non-NaN and non-BAD containing vectors, followed by the NaN vectors.
795  
796 =cut
797  
798 sub PDL::uniqvec {
799 my($pdl) = shift;
800  
801 return $pdl if ( $pdl->nelem == 0 || $pdl->ndims < 2 );
802 return $pdl if ( $pdl->slice("(0)")->nelem < 2 ); # slice isn't cheap but uniqvec isn't either
803  
804 my $pdl2d = $pdl->clump(1..$pdl->ndims-1);
805 my $ngood = $pdl2d->ngoodover;
806 $pdl2d = $pdl2d->mv(0,-1)->dice($ngood->which)->mv(-1,0); # remove all-BAD vectors
807  
808 my $numnan = ($pdl2d!=$pdl2d)->sumover; # works since no all-BADs to confuse
809  
810 my $presrt = $pdl2d->mv(0,-1)->dice($numnan->not->which)->mv(0,-1); # remove vectors with any NaN values
811 my $nanvec = $pdl2d->mv(0,-1)->dice($numnan->which)->mv(0,-1); # the vectors with any NaN values
812  
813 my $srt = $presrt->qsortvec->mv(0,-1); # BADs are sorted by qsortvec
814 my $srtdice = $srt;
815 my $somebad = null;
816 if ($srt->badflag) {
817 $srtdice = $srt->dice($srt->mv(0,-1)->nbadover->not->which);
818 $somebad = $srt->dice($srt->mv(0,-1)->nbadover->which);
819 }
820  
821 my $uniq = $srtdice->nelem > 0
822 ? ($srtdice != $srtdice->rotate(-1))->mv(0,-1)->orover->which
823 : $srtdice->orover->which;
824  
825 my $ans = $uniq->nelem > 0 ? $srtdice->dice($uniq) :
826 ($srtdice->nelem > 0) ? $srtdice->slice("0,:") :
827 $srtdice;
828 return $ans->append($somebad)->append($nanvec->mv(0,-1))->mv(0,-1);
829 }
830  
831 EOPM
832  
833 #####################################################################
834 # clipping routines
835 #####################################################################
836  
837 # clipping
838  
839 for my $opt ([qw(hclip PDLMIN upper)], [qw(lclip PDLMAX lower)]) {
840 my ($name, $op, $word) = @$opt;
841 pp_def(
842 $name,
843 HandleBad => 1,
844 Inplace => ['a'],
845 Pars => 'a(); b(); [o] c()',
846 Code =>
847 'PDL_IF_BAD(if ( $ISBAD(a()) || $ISBAD(b()) ) { $SETBAD(c()); continue; },)
848 '.'$c() = '.$op.'($b(), $a());',
849 Doc => 'clip (threshold) C<$a> by C<$b> (C<$b> is '.$word.' bound)',
850 );
851 }
852  
853 pp_def('clip',
854 HandleBad => 1,
855 Pars => 'a(); l(); h(); [o] c()',
856 Code => <<'EOBC',
857 PDL_IF_BAD(
858 if ($ISBAD(a()) || $ISBAD(l()) || $ISBAD(h())) { $SETBAD(c()); continue; },
859 )
860 $c() = PDLMIN($h(), PDLMAX($l(), $a()));
861 EOBC
862 Doc => <<'EOD',
863 =for ref
864  
865 Clip (threshold) an ndarray by (optional) upper or lower bounds.
866  
867 =for usage
868  
869 $y = $x->clip(0,3);
870 $c = $x->clip(undef, $x);
871 EOD
872 PMCode=>pp_line_numbers(__LINE__, <<'EOPM'),
873 *clip = \&PDL::clip;
874 sub PDL::clip {
875 my($x, $l, $h) = @_;
876 return $x->new_or_inplace if !defined($l) && !defined($h);
877 return $x->lclip($l) if !defined($h);
878 return $x->hclip($h) if !defined($l);
879 my $d;
880 if ($x->is_inplace) {
881 $x->set_inplace(0); $d = $x
882 } elsif (@_ > 3) {
883 $d=$_[3]
884 } else {
885 $d = PDL->nullcreate($x);
886 }
887 PDL::_clip_int($x,$l,$h,$d);
888 $d;
889 }
890 EOPM
891 );
892  
893 ############################################################
894 # elementary statistics and histograms
895 ############################################################
896  
897 pp_def('wtstat',
898 HandleBad => 1,
899 Pars => 'a(n); wt(n); avg(); [o]b();',
900 GenericTypes => [ppdefs_all],
901 OtherPars => 'int deg',
902 Code => <<'EOF',
903 complex long double wtsum = 0;
904 complex long double statsum = 0;
905 PDL_IF_BAD(int flag = 0;,)
906 loop(n) %{
907 PDL_IF_BAD(if ($ISBAD(wt()) || $ISBAD(a()) || $ISBAD(avg())) continue;flag = 1;,)
908 PDL_Indx i;
909 wtsum += $wt();
910 complex long double tmp=1;
911 for(i=0; i<$COMP(deg); i++)
912 tmp *= $a();
913 statsum += $wt() * (tmp - $avg());
914 %}
915 PDL_IF_BAD(if (!flag) { $SETBAD(b()); $PDLSTATESETBAD(b); }
916 else,) { $b() = statsum / wtsum; }
917 EOF
918 Doc => '
919 =for ref
920  
921 Weighted statistical moment of given degree
922  
923 This calculates a weighted statistic over the vector C<a>.
924 The formula is
925  
926 b() = (sum_i wt_i * (a_i ** degree - avg)) / (sum_i wt_i)
927 ',
928 BadDoc => '
929 Bad values are ignored in any calculation; C<$b> will only
930 have its bad flag set if the output contains any bad data.
931 ',
932 );
933  
934 pp_def('statsover',
935 HandleBad => 1,
936 Pars => 'a(n); w(n); float+ [o]avg(); float+ [o]prms(); int+ [o]min(); int+ [o]max(); float+ [o]adev(); float+ [o]rms()',
937 Code => <<'EOF',
938 PDL_IF_GENTYPE_REAL(PDL_LDouble,PDL_CLDouble) tmp = 0, tmp1 = 0, diff = 0;
939 $GENERIC(min) curmin = 0, curmax = 0;
940 $GENERIC(w) norm = 0;
941 int flag = 0;
942 loop(n) %{ /* Accumulate sum and summed weight. */
943 /* perhaps should check w() for bad values too ? */
944 PDL_IF_BAD(if (!( $ISGOOD(a()) )) continue;,)
945 tmp += $a()*$w();
946 norm += ($GENERIC(avg)) $w();
947 if (!flag) { curmin = $a(); curmax = $a(); flag=1; }
948 if ($a() < curmin) {
949 curmin = $a();
950 } else if ($a() > curmax) {
951 curmax = $a();
952 }
953 %}
954 /* have at least one valid point if flag true */
955 PDL_IF_BAD(if ( !flag ) {
956 $SETBAD(avg()); $PDLSTATESETBAD(avg);
957 $SETBAD(rms()); $PDLSTATESETBAD(rms);
958 $SETBAD(adev()); $PDLSTATESETBAD(adev);
959 $SETBAD(min()); $PDLSTATESETBAD(min);
960 $SETBAD(max()); $PDLSTATESETBAD(max);
961 $SETBAD(prms()); $PDLSTATESETBAD(prms);
962 continue;
963 },)
964 $avg() = tmp / norm; /* Find mean */
965 $min() = curmin;
966 $max() = curmax;
967 /* Calculate the RMS and standard deviation. */
968 tmp = 0;
969 loop(n) %{
970 PDL_IF_BAD(if (!$ISGOOD(a())) continue;,)
971 diff = $a()-$avg();
972 tmp += diff * diff * $w();
973 tmp1 += PDL_IF_GENTYPE_REAL(fabsl,cabsl)(diff) * $w();
974 %}
975 $rms() = sqrtl( tmp/norm );
976 if (norm>1)
977 $prms() = sqrtl( tmp/(norm-1) );
978 else
979 PDL_IF_BAD($SETBAD(prms()),$prms() = 0);
980 $adev() = tmp1 / norm ;
981 EOF
982 PMCode=>pp_line_numbers(__LINE__, <<'EOPM'),
983 sub PDL::statsover {
984 barf('Usage: ($mean,[$prms, $median, $min, $max, $adev, $rms]) = statsover($data,[$weights])') if @_>2;
985 my ($data, $weights) = @_;
986 $weights //= $data->ones();
987 my $median = $data->medover;
988 my $mean = PDL->nullcreate($data);
989 my $rms = PDL->nullcreate($data);
990 my $min = PDL->nullcreate($data);
991 my $max = PDL->nullcreate($data);
992 my $adev = PDL->nullcreate($data);
993 my $prms = PDL->nullcreate($data);
994 PDL::_statsover_int($data, $weights, $mean, $prms, $min, $max, $adev, $rms);
995 wantarray ? ($mean, $prms, $median, $min, $max, $adev, $rms) : $mean;
996 }
997 EOPM
998 Doc => '
999 =for ref
1000  
1001 Calculate useful statistics over a dimension of an ndarray
1002  
1003 =for usage
1004  
1005 ($mean,$prms,$median,$min,$max,$adev,$rms) = statsover($ndarray, $weights);
1006  
1007 This utility function calculates various useful
1008 quantities of an ndarray. These are:
1009  
1010 =over 3
1011  
1012 =item * the mean:
1013  
1014 MEAN = sum (x)/ N
1015  
1016 with C<N> being the number of elements in x
1017  
1018 =item * the population RMS deviation from the mean:
1019  
1020 PRMS = sqrt( sum( (x-mean(x))^2 )/(N-1) )
1021  
1022 The population deviation is the best-estimate of the deviation
1023 of the population from which a sample is drawn.
1024  
1025 =item * the median
1026  
1027 The median is the 50th percentile data value. Median is found by
1028 L<medover|PDL::Ufunc/medover>, so WEIGHTING IS IGNORED FOR THE MEDIAN CALCULATION.
1029  
1030 =item * the minimum
1031  
1032 =item * the maximum
1033  
1034 =item * the average absolute deviation:
1035  
1036 AADEV = sum( abs(x-mean(x)) )/N
1037  
1038 =item * RMS deviation from the mean:
1039  
1040 RMS = sqrt(sum( (x-mean(x))^2 )/N)
1041  
1042 (also known as the root-mean-square deviation, or the square root of the
1043 variance)
1044  
1045 =back
1046  
1047 This operator is a projection operator so the calculation
1048 will take place over the final dimension. Thus if the input
1049 is N-dimensional each returned value will be N-1 dimensional,
1050 to calculate the statistics for the entire ndarray either
1051 use C<clump(-1)> directly on the ndarray or call C<stats>.
1052 ',
1053 BadDoc =>'
1054 Bad values are simply ignored in the calculation, effectively reducing
1055 the sample size. If all data are bad then the output data are marked bad.
1056 ',
1057 );
1058  
1059 pp_add_exported('','stats');
1060 pp_addpm(<<'EOD');
1061 =head2 stats
1062  
1063 =for ref
1064  
1065 Calculates useful statistics on an ndarray
1066  
1067 =for usage
1068  
1069 ($mean,$prms,$median,$min,$max,$adev,$rms) = stats($ndarray,[$weights]);
1070  
1071 This utility calculates all the most useful quantities in one call.
1072 It works the same way as L</statsover>, except that the quantities are
1073 calculated considering the entire input PDL as a single sample, rather
1074 than as a collection of rows. See L</statsover> for definitions of the
1075 returned quantities.
1076  
1077 =for bad
1078  
1079 Bad values are handled; if all input values are bad, then all of the output
1080 values are flagged bad.
1081  
1082 =cut
1083  
1084 *stats = \&PDL::stats;
1085 sub PDL::stats {
1086 barf('Usage: ($mean,[$rms]) = stats($data,[$weights])') if @_>2;
1087 my ($data,$weights) = @_;
1088  
1089 # Ensure that $weights is properly broadcasted over; this could be
1090 # done rather more efficiently...
1091 if(defined $weights) {
1092 $weights = pdl($weights) unless UNIVERSAL::isa($weights,'PDL');
1093 if( ($weights->ndims != $data->ndims) or
1094 (pdl($weights->dims) != pdl($data->dims))->or
1095 ) {
1096 $weights = $weights + zeroes($data)
1097 }
1098 $weights = $weights->flat;
1099 }
1100  
1101 return PDL::statsover($data->flat,$weights);
1102 }
1103 EOD
1104  
1105 my $histogram_doc = <<'EOD';
1106 =for ref
1107  
1108 Calculates a histogram for given stepsize and minimum.
1109  
1110 =for usage
1111  
1112 $h = histogram($data, $step, $min, $numbins);
1113 $hist = zeroes $numbins; # Put histogram in existing ndarray.
1114 histogram($data, $hist, $step, $min, $numbins);
1115  
1116 The histogram will contain C<$numbins> bins starting from C<$min>, each
1117 C<$step> wide. The value in each bin is the number of
1118 values in C<$data> that lie within the bin limits.
1119  
1120  
1121 Data below the lower limit is put in the first bin, and data above the
1122 upper limit is put in the last bin.
1123  
1124 The output is reset in a different broadcastloop so that you
1125 can take a histogram of C<$a(10,12)> into C<$b(15)> and get the result
1126 you want.
1127  
1128 For a higher-level interface, see L<hist|PDL::Basic/hist>.
1129  
1130 =for example
1131  
1132 pdl> p histogram(pdl(1,1,2),1,0,3)
1133 [0 2 1]
1134  
1135 =cut
1136  
1137 EOD
1138  
1139 my $whistogram_doc = <<'EOD';
1140 =for ref
1141  
1142 Calculates a histogram from weighted data for given stepsize and minimum.
1143  
1144 =for usage
1145  
1146 $h = whistogram($data, $weights, $step, $min, $numbins);
1147 $hist = zeroes $numbins; # Put histogram in existing ndarray.
1148 whistogram($data, $weights, $hist, $step, $min, $numbins);
1149  
1150 The histogram will contain C<$numbins> bins starting from C<$min>, each
1151 C<$step> wide. The value in each bin is the sum of the values in C<$weights>
1152 that correspond to values in C<$data> that lie within the bin limits.
1153  
1154 Data below the lower limit is put in the first bin, and data above the
1155 upper limit is put in the last bin.
1156  
1157 The output is reset in a different broadcastloop so that you
1158 can take a histogram of C<$a(10,12)> into C<$b(15)> and get the result
1159 you want.
1160  
1161 =for example
1162  
1163 pdl> p whistogram(pdl(1,1,2), pdl(0.1,0.1,0.5), 1, 0, 4)
1164 [0 0.2 0.5 0]
1165  
1166 =cut
1167 EOD
1168  
1169 for(
1170 {Name => 'histogram',
1171 WeightPar => '',
1172 HistType => 'int+',
1173 HistOp => '+= 1',
1174 Doc => $histogram_doc,
1175 },
1176 {Name => 'whistogram',
1177 WeightPar => 'float+ wt(n);',
1178 HistType => 'float+',
1179 HistOp => '+= $wt()',
1180 Doc => $whistogram_doc,
1181 }
1182 )
1183 {
1184 pp_def($_->{Name},
1185 Pars => 'in(n); '.$_->{WeightPar}.$_->{HistType}. '[o] hist(m)',
1186 GenericTypes => [ppdefs_all],
1187 # set outdim by Par!
1188 OtherPars => 'double step; double min; IV msize => m',
1189 HandleBad => 1,
1190 RedoDimsCode => 'if ($SIZE(m) == 0) $CROAK("called with m dim of 0");',
1191 Code => pp_line_numbers(__LINE__-1, '
1192 register double min = $COMP(min), step = $COMP(step);
1193 broadcastloop %{
1194 loop(m) %{ $hist() = 0; %}
1195 loop(n) %{
1196 PDL_IF_BAD(if ( !$ISGOOD(in()) ) continue;,)
1197 PDL_Indx j = round((($in()-min)/step)-0.5);
1198 j = PDLMIN(PDLMAX(j, 0), $SIZE(m)-1);
1199 ($hist(m => j))'.$_->{HistOp}.';
1200 %}
1201 %}'),
1202 Doc=>$_->{Doc});
1203 }
1204  
1205 my $histogram2d_doc = <<'EOD';
1206 =for ref
1207  
1208 Calculates a 2d histogram.
1209  
1210 =for usage
1211  
1212 $h = histogram2d($datax, $datay, $stepx, $minx,
1213 $nbinx, $stepy, $miny, $nbiny);
1214 $hist = zeroes $nbinx, $nbiny; # Put histogram in existing ndarray.
1215 histogram2d($datax, $datay, $hist, $stepx, $minx,
1216 $nbinx, $stepy, $miny, $nbiny);
1217  
1218 The histogram will contain C<$nbinx> x C<$nbiny> bins, with the lower
1219 limits of the first one at C<($minx, $miny)>, and with bin size
1220 C<($stepx, $stepy)>.
1221 The value in each bin is the number of
1222 values in C<$datax> and C<$datay> that lie within the bin limits.
1223  
1224 Data below the lower limit is put in the first bin, and data above the
1225 upper limit is put in the last bin.
1226  
1227 =for example
1228  
1229 pdl> p histogram2d(pdl(1,1,1,2,2),pdl(2,1,1,1,1),1,0,3,1,0,3)
1230 [
1231 [0 0 0]
1232 [0 2 2]
1233 [0 1 0]
1234 ]
1235  
1236 =cut
1237 EOD
1238  
1239 my $whistogram2d_doc = <<'EOD';
1240 =for ref
1241  
1242 Calculates a 2d histogram from weighted data.
1243  
1244 =for usage
1245  
1246 $h = whistogram2d($datax, $datay, $weights,
1247 $stepx, $minx, $nbinx, $stepy, $miny, $nbiny);
1248 $hist = zeroes $nbinx, $nbiny; # Put histogram in existing ndarray.
1249 whistogram2d($datax, $datay, $weights, $hist,
1250 $stepx, $minx, $nbinx, $stepy, $miny, $nbiny);
1251  
1252 The histogram will contain C<$nbinx> x C<$nbiny> bins, with the lower
1253 limits of the first one at C<($minx, $miny)>, and with bin size
1254 C<($stepx, $stepy)>.
1255 The value in each bin is the sum of the values in
1256 C<$weights> that correspond to values in C<$datax> and C<$datay> that lie within the bin limits.
1257  
1258 Data below the lower limit is put in the first bin, and data above the
1259 upper limit is put in the last bin.
1260  
1261 =for example
1262  
1263 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)
1264 [
1265 [ 0 0 0]
1266 [ 0 0.5 0.9]
1267 [ 0 0.1 0]
1268 ]
1269  
1270 =cut
1271 EOD
1272  
1273 for(
1274 {Name => 'histogram2d',
1275 WeightPar => '',
1276 HistType => 'int+',
1277 HistOp => '+= 1',
1278 Doc => $histogram2d_doc,
1279 },
1280 {Name => 'whistogram2d',
1281 WeightPar => 'float+ wt(n);',
1282 HistType => 'float+',
1283 HistOp => '+= $wt()',
1284 Doc => $whistogram2d_doc,
1285 }
1286 )
1287 {
1288 pp_def($_->{Name},
1289 Pars => 'ina(n); inb(n); '.$_->{WeightPar}.$_->{HistType}. '[o] hist(ma,mb)',
1290 GenericTypes => [ppdefs_all],
1291 # set outdim by Par!
1292 OtherPars => 'double stepa; double mina; IV masize => ma;
1293 double stepb; double minb; IV mbsize => mb;',
1294 HandleBad => 1,
1295 RedoDimsCode => '
1296 if ($SIZE(ma) == 0) $CROAK("called with ma dim of 0");
1297 if ($SIZE(mb) == 0) $CROAK("called with mb dim of 0");
1298 ',
1299 Code => pp_line_numbers(__LINE__-1, '
1300 register double mina = $COMP(mina), minb = $COMP(minb), stepa = $COMP(stepa), stepb = $COMP(stepb);
1301 broadcastloop %{
1302 loop(ma,mb) %{ $hist() = 0; %}
1303 loop(n) %{
1304 PDL_IF_BAD(if (!( $ISGOOD(ina()) && $ISGOOD(inb()) )) continue;,)
1305 PDL_Indx ja = round((($ina()-mina)/stepa)-0.5);
1306 PDL_Indx jb = round((($inb()-minb)/stepb)-0.5);
1307 ja = PDLMIN(PDLMAX(ja, 0), $SIZE(ma)-1);
1308 jb = PDLMIN(PDLMAX(jb, 0), $SIZE(mb)-1);
1309 ($hist(ma => ja,mb => jb))'.$_->{HistOp}.';
1310 %}
1311 %}'),
1312 Doc=> $_->{Doc});
1313 }
1314  
1315  
1316 ###########################################################
1317 # a number of constructors: fibonacci, append, axisvalues &
1318 # random numbers
1319 ###########################################################
1320  
1321 pp_def('fibonacci',
1322 Pars => 'i(n); [o]x(n)',
1323 Inplace => 1,
1324 GenericTypes => [ppdefs_all],
1325 Doc=>'Constructor - a vector with Fibonacci\'s sequence',
1326 PMFunc=>'',
1327 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1328 sub fibonacci { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->fibonacci : PDL->fibonacci(@_) }
1329 sub PDL::fibonacci{
1330 my $x = &PDL::Core::_construct;
1331 my $is_inplace = $x->is_inplace;
1332 my ($in, $out) = $x->flat;
1333 $out = $is_inplace ? $in->inplace : PDL->null;
1334 PDL::_fibonacci_int($in, $out);
1335 $out;
1336 }
1337 EOD
1338 Code => '
1339 PDL_Indx i=0;
1340 $GENERIC() x1, x2;
1341 x1 = 1; x2 = 0;
1342 loop(n) %{
1343 $x() = x1 + x2;
1344 if (i++>0) {
1345 x2 = x1;
1346 x1 = $x();
1347 }
1348 %}
1349 ');
1350  
1351 pp_def('append',
1352 Pars => 'a(n); b(m); [o] c(mn=CALC($SIZE(n)+$SIZE(m)))',
1353 GenericTypes => [ppdefs_all],
1354 PMCode => pp_line_numbers(__LINE__-1, '
1355 sub PDL::append {
1356 my ($i1, $i2, $o) = map PDL->topdl($_), @_;
1357 $_ = empty() for grep $_->isnull, $i1, $i2;
1358 my $nempty = grep $_->isempty, $i1, $i2;
1359 if ($nempty == 2) {
1360 my @dims = $i1->dims;
1361 $dims[0] += $i2->dim(0);
1362 return PDL->zeroes($i1->type, @dims);
1363 }
1364 $o //= PDL->null;
1365 $o .= $i1->isempty ? $i2 : $i1, return $o if $nempty == 1;
1366 PDL::_append_int($i1, $i2->convert($i1->type), $o);
1367 $o;
1368 }
1369 '),
1370 Code => 'PDL_Indx ns = $SIZE(n);
1371 broadcastloop %{
1372 loop(n) %{ $c(mn => n) = $a(); %}
1373 loop(mn=ns) %{ $c() = $b(m=>mn-ns); %}
1374 %}',
1375 Doc => '
1376 =for ref
1377  
1378 append two ndarrays by concatenating along their first dimensions
1379  
1380 =for example
1381  
1382 $x = ones(2,4,7);
1383 $y = sequence 5;
1384 $c = $x->append($y); # size of $c is now (7,4,7) (a jumbo-ndarray ;)
1385  
1386 C<append> appends two ndarrays along their first dimensions. The rest of the
1387 dimensions must be compatible in the broadcasting sense. The resulting
1388 size of the first dimension is the sum of the sizes of the first dimensions
1389 of the two argument ndarrays - i.e. C<n + m>.
1390  
1391 Similar functions include L</glue> (below), which can append more
1392 than two ndarrays along an arbitrary dimension, and
1393 L<cat|PDL::Core/cat>, which can append more than two ndarrays that all
1394 have the same sized dimensions.
1395 '
1396 );
1397  
1398 pp_addpm(<<'EOD');
1399 =head2 glue
1400  
1401 =for usage
1402  
1403 $c = $x->glue(<dim>,$y,...)
1404  
1405 =for ref
1406  
1407 Glue two or more PDLs together along an arbitrary dimension
1408 (N-D L</append>).
1409  
1410 Sticks $x, $y, and all following arguments together along the
1411 specified dimension. All other dimensions must be compatible in the
1412 broadcasting sense.
1413  
1414 Glue is permissive, in the sense that every PDL is treated as having an
1415 infinite number of trivial dimensions of order 1 -- so C<< $x->glue(3,$y) >>
1416 works, even if $x and $y are only one dimensional.
1417  
1418 If one of the PDLs has no elements, it is ignored. Likewise, if one
1419 of them is actually the undefined value, it is treated as if it had no
1420 elements.
1421  
1422 If the first parameter is a defined perl scalar rather than a pdl,
1423 then it is taken as a dimension along which to glue everything else,
1424 so you can say C<$cube = PDL::glue(3,@image_list);> if you like.
1425  
1426 C<glue> is implemented in pdl, using a combination of L<xchg|PDL::Slices/xchg> and
1427 L</append>. It should probably be updated (one day) to a pure PP
1428 function.
1429  
1430 Similar functions include L</append> (above), which appends
1431 only two ndarrays along their first dimension, and
1432 L<cat|PDL::Core/cat>, which can append more than two ndarrays that all
1433 have the same sized dimensions.
1434  
1435 =cut
1436  
1437 sub PDL::glue {
1438 my ($x, $dim) = splice @_, 0, 2;
1439 ($dim, $x) = ($x, $dim) if defined $x && !ref $x;
1440 confess 'dimension must be Perl scalar' if ref $dim;
1441 if (!defined $x || $x->nelem==0) {
1442 return $x unless @_;
1443 return shift if @_<=1;
1444 $x = shift;
1445 return PDL::glue($x,$dim,@_);
1446 }
1447 if ($dim - $x->dim(0) > 100) {
1448 warn "warning: PDL::glue allocating >100 dimensions!\n";
1449 }
1450 while ($dim >= $x->ndims) {
1451 $x = $x->dummy(-1,1);
1452 }
1453 $x = $x->xchg(0,$dim) if 0 != $dim;
1454 while (@_) {
1455 my $y = shift;
1456 next unless defined $y && $y->nelem;
1457 while ($dim >= $y->ndims) {
1458 $y = $y->dummy(-1,1);
1459 }
1460 $y = $y->xchg(0,$dim) if 0 != $dim;
1461 $x = $x->append($y);
1462 }
1463 0 == $dim ? $x : $x->xchg(0,$dim);
1464 }
1465  
1466 EOD
1467  
1468 pp_def( 'axisvalues',
1469 Pars => 'i(n); [o]a(n)',
1470 Inplace => 1,
1471 Code => 'loop(n) %{ $a() = n; %}',
1472 GenericTypes => [ppdefs_all],
1473 Doc => undef,
1474 ); # pp_def: axisvalues
1475  
1476 pp_add_macros(
1477 CMPVEC => sub {
1478 my ($a, $b, $dim, $ret, $anybad) = @_;
1479 my $badbit = !defined $anybad ? '' : <<EOF;
1480 PDL_IF_BAD(if (\$ISBAD($a) || \$ISBAD($b)) { $anybad = 1; break; } else,)
1481 EOF
1482 <<EOF;
1483 $ret = 0;
1484 loop($dim) %{ $badbit if ($a != $b) { $ret = $a < $b ? -1 : 1; break; } %}
1485 EOF
1486 },
1487 );
1488  
1489 pp_def(
1490 'cmpvec',
1491 HandleBad => 1,
1492 Pars => 'a(n); b(n); sbyte [o]c();',
1493 Code => '
1494 PDL_IF_BAD(char anybad = 0;,)
1495 broadcastloop %{
1496 $CMPVEC($a(), $b(), n, $c(), anybad);
1497 PDL_IF_BAD(if (anybad) $SETBAD(c());,)
1498 %}
1499 PDL_IF_BAD(if (anybad) $PDLSTATESETBAD(c);,)
1500 ',
1501 Doc => '
1502 =for ref
1503  
1504 Compare two vectors lexicographically.
1505  
1506 Returns -1 if a is less, 1 if greater, 0 if equal.
1507 ',
1508 BadDoc => '
1509 The output is bad if any input values up to the point of inequality are
1510 bad - any after are ignored.
1511 ',
1512 );
1513  
1514 pp_def(
1515 'eqvec',
1516 HandleBad => 1,
1517 Pars => 'a(n); b(n); sbyte [o]c();',
1518 Code => '
1519 PDL_IF_BAD(char anybad = 0;,)
1520 broadcastloop %{
1521 $c() = 1;
1522 loop(n) %{
1523 PDL_IF_BAD(if ($ISBAD(a()) || $ISBAD(b())) { $SETBAD(c()); anybad = 1; break; }
1524 else,) if ($a() != $b()) { $c() = 0; PDL_IF_BAD(,break;) }
1525 %}
1526 %}
1527 PDL_IF_BAD(if (anybad) $PDLSTATESETBAD(c);,)
1528 ',
1529 Doc => 'Compare two vectors, returning 1 if equal, 0 if not equal.',
1530 BadDoc => 'The output is bad if any input values are bad.',
1531 );
1532  
1533 pp_def('enumvec',
1534 Pars => 'v(M,N); indx [o]k(N)',
1535 Code => pp_line_numbers(__LINE__, <<'EOC'),
1536 loop (N) %{
1537 PDL_Indx vn = N; /* preserve value of N into inner N loop */
1538 loop (N=vn) %{
1539 if (N == vn) { $k() = 0; continue; } /* no need to compare with self */
1540 char matches = 1;
1541 loop (M) %{
1542 if ($v(N=>vn) == $v()) continue;
1543 matches = 0;
1544 break;
1545 %}
1546 if (matches) {
1547 $k() = N-vn;
1548 if (N == $SIZE(N)-1) vn = N; /* last one matched, so stop */
1549 } else {
1550 vn = N-1;
1551 break;
1552 }
1553 %}
1554 N = vn; /* skip forward */
1555 %}
1556 EOC
1557 Doc =><<'EOD',
1558 =for ref
1559  
1560 Enumerate a list of vectors with locally unique keys.
1561  
1562 Given a sorted list of vectors $v, generate a vector $k containing locally unique keys for the elements of $v
1563 (where an "element" is a vector of length $M occurring in $v).
1564  
1565 Note that the keys returned in $k are only unique over a run of a single vector in $v,
1566 so that each unique vector in $v has at least one 0 (zero) index in $k associated with it.
1567 If you need global keys, see enumvecg().
1568  
1569 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1570 EOD
1571 );
1572  
1573 ##------------------------------------------------------
1574 ## enumvecg()
1575 pp_def('enumvecg',
1576 Pars => 'v(M,N); indx [o]k(N)',
1577 Code =><<'EOC',
1578 if (!$SIZE(N)) return PDL_err;
1579 PDL_Indx Nprev = 0, ki = $k(N=>0) = 0;
1580 loop(N=1) %{
1581 loop (M) %{
1582 if ($v(N=>Nprev) == $v()) continue;
1583 ++ki;
1584 break;
1585 %}
1586 $k() = ki;
1587 Nprev = N;
1588 %}
1589 EOC
1590 Doc =><<'EOD',
1591 =for ref
1592  
1593 Enumerate a list of vectors with globally unique keys.
1594  
1595 Given a sorted list of vectors $v, generate a vector $k containing globally unique keys for the elements of $v
1596 (where an "element" is a vector of length $M occurring in $v).
1597 Basically does the same thing as:
1598  
1599 $k = $v->vsearchvec($v->uniqvec);
1600  
1601 ... but somewhat more efficiently.
1602  
1603 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1604 EOD
1605 );
1606  
1607 pp_def('vsearchvec',
1608 Pars => 'find(M); which(M,N); indx [o]found();',
1609 Code => q(
1610 int carp=0;
1611 broadcastloop %{
1612 PDL_Indx n1=$SIZE(N)-1, nlo=-1, nhi=n1, nn;
1613 int cmpval, is_asc_sorted;
1614 //
1615 //-- get sort direction
1616 $CMPVEC($which(N=>n1),$which(N=>0),M,cmpval);
1617 is_asc_sorted = (cmpval > 0);
1618 //
1619 //-- binary search
1620 while (nhi-nlo > 1) {
1621 nn = (nhi+nlo) >> 1;
1622 $CMPVEC($find(),$which(N=>nn),M,cmpval);
1623 if ((cmpval > 0) == is_asc_sorted)
1624 nlo=nn;
1625 else
1626 nhi=nn;
1627 }
1628 if (nlo==-1) {
1629 nhi=0;
1630 } else if (nlo==n1) {
1631 $CMPVEC($find(),$which(N=>n1),M,cmpval);
1632 if (cmpval != 0) carp = 1;
1633 nhi = n1;
1634 } else {
1635 nhi = nlo+1;
1636 }
1637 $found() = nhi;
1638 %}
1639 if (carp) warn("some values had to be extrapolated");
1640 ),
1641 Doc=><<'EOD'
1642 =for ref
1643  
1644 Routine for searching N-dimensional values - akin to vsearch() for vectors.
1645  
1646 =for example
1647  
1648 $found = vsearchvec($find, $which);
1649 $nearest = $which->dice_axis(1,$found);
1650  
1651 Returns for each row-vector in C<$find> the index along dimension N
1652 of the least row vector of C<$which>
1653 greater or equal to it.
1654 C<$which> should be sorted in increasing order.
1655 If the value of C<$find> is larger
1656 than any member of C<$which>, the index to the last element of C<$which> is
1657 returned.
1658  
1659 See also: L</vsearch>.
1660 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1661 EOD
1662 );
1663  
1664 pp_def('unionvec',
1665 Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC($SIZE(NA) + $SIZE(NB))); indx [o]nc()',
1666 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1667 sub PDL::unionvec {
1668 my ($a,$b,$c,$nc) = @_;
1669 $c = PDL->null if (!defined($nc));
1670 $nc = PDL->null if (!defined($nc));
1671 PDL::_unionvec_int($a,$b,$c,$nc);
1672 return ($c,$nc) if (wantarray);
1673 return $c->slice(",0:".($nc->max-1));
1674 }
1675 EOD
1676 Code => q(
1677 PDL_Indx nai=0, nbi=0, nci=$SIZE(NC), sizeNA=$SIZE(NA), sizeNB=$SIZE(NB);
1678 int cmpval;
1679 loop (NC) %{
1680 if (nai < sizeNA && nbi < sizeNB) {
1681 $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval);
1682 }
1683 else if (nai < sizeNA) { cmpval = -1; }
1684 else if (nbi < sizeNB) { cmpval = 1; }
1685 else { nci=NC; break; }
1686 //
1687 if (cmpval < 0) {
1688 //-- CASE: a < b
1689 loop (M) %{ $c() = $a(NA=>nai); %}
1690 nai++;
1691 }
1692 else if (cmpval > 0) {
1693 //-- CASE: a > b
1694 loop (M) %{ $c() = $b(NB=>nbi); %}
1695 nbi++;
1696 }
1697 else {
1698 //-- CASE: a == b
1699 loop (M) %{ $c() = $a(NA=>nai); %}
1700 nai++;
1701 nbi++;
1702 }
1703 %}
1704 $nc() = nci;
1705 //-- zero unpopulated outputs
1706 loop(NC=nci,M) %{ $c() = 0; %}
1707 ),
1708 Doc=><<'EOD'
1709 =for ref
1710  
1711 Union of two vector-valued PDLs.
1712  
1713 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order.
1714 On return, $nc() holds the actual number of vector-values in the union.
1715  
1716 In scalar context, slices $c() to the actual number of elements in the union
1717 and returns the sliced PDL.
1718  
1719 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1720 EOD
1721 );
1722  
1723 pp_def('intersectvec',
1724 Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC(PDLMIN($SIZE(NA),$SIZE(NB)))); indx [o]nc()',
1725 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1726 sub PDL::intersectvec {
1727 my ($a,$b,$c,$nc) = @_;
1728 $c = PDL->null if (!defined($c));
1729 $nc = PDL->null if (!defined($nc));
1730 PDL::_intersectvec_int($a,$b,$c,$nc);
1731 return ($c,$nc) if (wantarray);
1732 my $nc_max = $nc->max;
1733 return ($nc_max > 0
1734 ? $c->slice(",0:".($nc_max-1))
1735 : $c->reshape($c->dim(0), 0, ($c->dims)[2..($c->ndims-1)]));
1736 }
1737 EOD
1738 Code => q(
1739 PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC);
1740 int cmpval;
1741 for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB; ) {
1742 $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval);
1743 //
1744 if (cmpval < 0) {
1745 //-- CASE: a < b
1746 nai++;
1747 }
1748 else if (cmpval > 0) {
1749 //-- CASE: a > b
1750 nbi++;
1751 }
1752 else {
1753 //-- CASE: a == b
1754 loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %}
1755 nai++;
1756 nbi++;
1757 nci++;
1758 }
1759 }
1760 $nc() = nci;
1761 //-- zero unpopulated outputs
1762 loop(NC=nci,M) %{ $c() = 0; %}
1763 ),
1764 Doc=><<'EOD'
1765 =for ref
1766  
1767 Intersection of two vector-valued PDLs.
1768 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order.
1769 On return, $nc() holds the actual number of vector-values in the intersection.
1770  
1771 In scalar context, slices $c() to the actual number of elements in the intersection
1772 and returns the sliced PDL.
1773  
1774 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1775 EOD
1776 );
1777  
1778 pp_def('setdiffvec',
1779 Pars => 'a(M,NA); b(M,NB); [o]c(M,NC=CALC($SIZE(NA))); indx [o]nc()',
1780 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1781 sub PDL::setdiffvec {
1782 my ($a,$b,$c,$nc) = @_;
1783 $c = PDL->null if (!defined($c));
1784 $nc = PDL->null if (!defined($nc));
1785 PDL::_setdiffvec_int($a,$b,$c,$nc);
1786 return ($c,$nc) if (wantarray);
1787 my $nc_max = $nc->max;
1788 return ($nc_max > 0
1789 ? $c->slice(",0:".($nc_max-1))
1790 : $c->reshape($c->dim(0), 0, ($c->dims)[2..($c->ndims-1)]));
1791 }
1792 EOD
1793 Code => q(
1794 PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC);
1795 int cmpval;
1796 for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB ; ) {
1797 $CMPVEC($a(NA=>nai),$b(NB=>nbi),M,cmpval);
1798 //
1799 if (cmpval < 0) {
1800 //-- CASE: a < b
1801 loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %}
1802 nai++;
1803 nci++;
1804 }
1805 else if (cmpval > 0) {
1806 //-- CASE: a > b
1807 nbi++;
1808 }
1809 else {
1810 //-- CASE: a == b
1811 nai++;
1812 nbi++;
1813 }
1814 }
1815 for ( ; nci < sizeNC && nai < sizeNA ; nai++,nci++ ) {
1816 loop (M) %{ $c(NC=>nci) = $a(NA=>nai); %}
1817 }
1818 $nc() = nci;
1819 //-- zero unpopulated outputs
1820 loop (NC=nci,M) %{ $c() = 0; %}
1821 ),
1822 Doc=><<'EOD'
1823 =for ref
1824  
1825 Set-difference ($a() \ $b()) of two vector-valued PDLs.
1826  
1827 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order.
1828 On return, $nc() holds the actual number of vector-values in the computed vector set.
1829  
1830 In scalar context, slices $c() to the actual number of elements in the output vector set
1831 and returns the sliced PDL.
1832  
1833 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1834 EOD
1835 );
1836  
1837 pp_add_macros(
1838 CMPVAL => sub {
1839 my ($val1, $val2) = @_;
1840 "(($val1) < ($val2) ? -1 : ($val1) > ($val2) ? 1 : 0)";
1841 },
1842 );
1843  
1844 pp_def('union_sorted',
1845 Pars => 'a(NA); b(NB); [o]c(NC=CALC($SIZE(NA) + $SIZE(NB))); indx [o]nc()',
1846 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1847 sub PDL::union_sorted {
1848 my ($a,$b,$c,$nc) = @_;
1849 $c = PDL->null if (!defined($c));
1850 $nc = PDL->null if (!defined($nc));
1851 PDL::_union_sorted_int($a,$b,$c,$nc);
1852 return ($c,$nc) if (wantarray);
1853 return $c->slice("0:".($nc->max-1));
1854 }
1855 EOD
1856 Code => q(
1857 PDL_Indx nai=0, nbi=0, nci=$SIZE(NC), sizeNA=$SIZE(NA), sizeNB=$SIZE(NB);
1858 int cmpval;
1859 loop (NC) %{
1860 if (nai < sizeNA && nbi < sizeNB) {
1861 cmpval = $CMPVAL($a(NA=>nai), $b(NB=>nbi));
1862 }
1863 else if (nai < sizeNA) { cmpval = -1; }
1864 else if (nbi < sizeNB) { cmpval = 1; }
1865 else { nci = NC; break; }
1866 //
1867 if (cmpval < 0) {
1868 //-- CASE: a < b
1869 $c() = $a(NA=>nai);
1870 nai++;
1871 }
1872 else if (cmpval > 0) {
1873 //-- CASE: a > b
1874 $c() = $b(NB=>nbi);
1875 nbi++;
1876 }
1877 else {
1878 //-- CASE: a == b
1879 $c() = $a(NA=>nai);
1880 nai++;
1881 nbi++;
1882 }
1883 %}
1884 $nc() = nci;
1885 loop (NC=nci) %{
1886 //-- zero unpopulated outputs
1887 $c() = 0;
1888 %}
1889 ),
1890 Doc=><<'EOD'
1891 =for ref
1892  
1893 Union of two flat sorted unique-valued PDLs.
1894 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order and contain no duplicates.
1895 On return, $nc() holds the actual number of values in the union.
1896  
1897 In scalar context, reshapes $c() to the actual number of elements in the union and returns it.
1898  
1899 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1900 EOD
1901 );
1902  
1903 pp_def('intersect_sorted',
1904 Pars => 'a(NA); b(NB); [o]c(NC=CALC(PDLMIN($SIZE(NA),$SIZE(NB)))); indx [o]nc()',
1905 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1906 sub PDL::intersect_sorted {
1907 my ($a,$b,$c,$nc) = @_;
1908 $c = PDL->null if (!defined($c));
1909 $nc = PDL->null if (!defined($nc));
1910 PDL::_intersect_sorted_int($a,$b,$c,$nc);
1911 return ($c,$nc) if (wantarray);
1912 my $nc_max = $nc->max;
1913 return ($nc_max > 0
1914 ? $c->slice("0:".($nc_max-1))
1915 : $c->reshape(0, ($c->dims)[1..($c->ndims-1)]));
1916 }
1917 EOD
1918 Code => q(
1919 PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC);
1920 int cmpval;
1921 for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB; ) {
1922 cmpval = $CMPVAL($a(NA=>nai),$b(NB=>nbi));
1923 //
1924 if (cmpval < 0) {
1925 //-- CASE: a < b
1926 nai++;
1927 }
1928 else if (cmpval > 0) {
1929 //-- CASE: a > b
1930 nbi++;
1931 }
1932 else {
1933 //-- CASE: a == b
1934 $c(NC=>nci) = $a(NA=>nai);
1935 nai++;
1936 nbi++;
1937 nci++;
1938 }
1939 }
1940 $nc() = nci;
1941 for ( ; nci < sizeNC; nci++) {
1942 //-- zero unpopulated outputs
1943 $c(NC=>nci) = 0;
1944 }
1945 ),
1946 Doc=><<'EOD'
1947 =for ref
1948  
1949 Intersection of two flat sorted unique-valued PDLs.
1950 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order and contain no duplicates.
1951 On return, $nc() holds the actual number of values in the intersection.
1952  
1953 In scalar context, reshapes $c() to the actual number of elements in the intersection and returns it.
1954  
1955 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1956 EOD
1957 );
1958  
1959 pp_def('setdiff_sorted',
1960 Pars => 'a(NA); b(NB); [o]c(NC=CALC($SIZE(NA))); indx [o]nc()',
1961 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
1962 sub PDL::setdiff_sorted {
1963 my ($a,$b,$c,$nc) = @_;
1964 $c = PDL->null if (!defined($c));
1965 $nc = PDL->null if (!defined($nc));
1966 PDL::_setdiff_sorted_int($a,$b,$c,$nc);
1967 return ($c,$nc) if (wantarray);
1968 my $nc_max = $nc->max;
1969 return ($nc_max > 0
1970 ? $c->slice("0:".($nc_max-1))
1971 : $c->reshape(0, ($c->dims)[1..($c->ndims-1)]));
1972 }
1973 EOD
1974 Code => q(
1975 PDL_Indx nai=0, nbi=0, nci=0, sizeNA=$SIZE(NA), sizeNB=$SIZE(NB), sizeNC=$SIZE(NC);
1976 int cmpval;
1977 for ( ; nci < sizeNC && nai < sizeNA && nbi < sizeNB ; ) {
1978 cmpval = $CMPVAL($a(NA=>nai),$b(NB=>nbi));
1979 //
1980 if (cmpval < 0) {
1981 //-- CASE: a < b
1982 $c(NC=>nci) = $a(NA=>nai);
1983 nai++;
1984 nci++;
1985 }
1986 else if (cmpval > 0) {
1987 //-- CASE: a > b
1988 nbi++;
1989 }
1990 else {
1991 //-- CASE: a == b
1992 nai++;
1993 nbi++;
1994 }
1995 }
1996 for ( ; nci < sizeNC && nai < sizeNA ; nai++,nci++ ) {
1997 $c(NC=>nci) = $a(NA=>nai);
1998 }
1999 $nc() = nci;
2000 for ( ; nci < sizeNC; nci++) {
2001 //-- zero unpopulated outputs
2002 $c(NC=>nci) = 0;
2003 }
2004 ),
2005 Doc=><<'EOD'
2006 =for ref
2007  
2008 Set-difference ($a() \ $b()) of two flat sorted unique-valued PDLs.
2009  
2010 Input PDLs $a() and $b() B<MUST> be sorted in lexicographic order and contain no duplicate values.
2011 On return, $nc() holds the actual number of values in the computed vector set.
2012  
2013 In scalar context, reshapes $c() to the actual number of elements in the difference set and returns it.
2014  
2015 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
2016 EOD
2017 );
2018  
2019 pp_def('vcos',
2020 Pars => join('',
2021 "a(M,N);", ##-- logical (D,T)
2022 "b(M);", ##-- logical (D,1)
2023 "float+ [o]vcos(N);", ##-- logical (T)
2024 ),
2025 GenericTypes => [ppdefs_all],
2026 HandleBad => 1,
2027 Code => pp_line_numbers(__LINE__, <<'EOF'),
2028 broadcastloop %{
2029 $GENERIC(vcos) bnorm = 0;
2030 loop(M) %{
2031 PDL_IF_BAD(if ($ISBAD(b())) continue;,)
2032 bnorm += $b() * $b();
2033 %}
2034 if (bnorm == 0) {
2035 /*-- null-vector b(): set all vcos()=NAN --*/
2036 loop (N) %{ $vcos() = NAN; %}
2037 continue;
2038 }
2039 bnorm = sqrtl(bnorm);
2040 /*-- usual case: compute values for N-slice of b() --*/
2041 loop (N) %{
2042 $GENERIC(vcos) anorm = 0, vval = 0;
2043 loop (M) %{
2044 PDL_IF_BAD(if ($ISBAD(a())) continue;,)
2045 $GENERIC(vcos) aval = $a();
2046 anorm += aval * aval;
2047 PDL_IF_BAD(if ($ISBAD(b())) continue;,)
2048 vval += aval * $b();
2049 %}
2050 /*-- normalize --*/
2051 anorm = sqrtl(anorm);
2052 if (anorm != 0) {
2053 /*-- usual case a(), b() non-null --*/
2054 $vcos() = vval / (anorm * bnorm);
2055 } else {
2056 /*-- null-vector a(): set vcos()=NAN --*/
2057 $vcos() = NAN;
2058 }
2059 %}
2060 %}
2061 if ( $PDLSTATEISBAD(a) || $PDLSTATEISBAD(b) )
2062 $PDLSTATESETBAD(vcos);
2063 EOF
2064 Doc => q{
2065 Computes the vector cosine similarity of a dense vector $b() with respect
2066 to each row $a(*,i) of a dense PDL $a(). This is basically the same
2067 thing as:
2068  
2069 inner($a, $b) / $a->magnover * $b->magnover
2070  
2071 ... but should be much faster to compute, and avoids allocating
2072 potentially large temporaries for the vector magnitudes. Output values
2073 in $vcos() are cosine similarities in the range [-1,1], except for
2074 zero-magnitude vectors which will result in NaN values in $vcos().
2075  
2076 You can use PDL broadcasting to batch-compute distances for multiple $b()
2077 vectors simultaneously:
2078  
2079 $bx = random($M, $NB); ##-- get $NB random vectors of size $N
2080 $vcos = vcos($a,$bx); ##-- $vcos(i,j) ~ sim($a(,i),$b(,j))
2081  
2082 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
2083 },
2084 BadDoc=> q{
2085 vcos() will set the bad status flag on the output $vcos() if
2086 it is set on either of the inputs $a() or $b(), but BAD values
2087 will otherwise be ignored for computing the cosine similarity.
2088 },
2089 );
2090  
2091 pp_addhdr(<<'EOH');
2092 extern int pdl_srand_threads;
2093 extern uint64_t *pdl_rand_state;
2094 void pdl_srand(uint64_t **s, uint64_t seed, int n);
2095 double pdl_drand(uint64_t *s);
2096 #define PDL_MAYBE_SRAND \
2097 if (pdl_srand_threads < 0) \
2098 pdl_srand(&pdl_rand_state, PDL->pdl_seed(), PDL->online_cpus());
2099 #define PDL_RAND_SET_OFFSET(v, thr, pdl) \
2100 if (v < 0) { \
2101 if (thr.mag_nthr >= 0) { \
2102 int thr_no = PDL->magic_get_thread(pdl); \
2103 if (thr_no < 0) return PDL->make_error_simple(PDL_EFATAL, "Invalid pdl_magic_get_thread!"); \
2104 v = thr_no == 0 ? thr_no : thr_no % PDL->online_cpus(); \
2105 } else { \
2106 v = 0; \
2107 } \
2108 }
2109 EOH
2110  
2111 pp_def(
2112 'srandom',
2113 Pars=>'a();',
2114 GenericTypes => ['Q'],
2115 Code => <<'EOF',
2116 pdl_srand(&pdl_rand_state, (uint64_t)$a(), PDL->online_cpus());
2117 EOF
2118 NoPthread => 1,
2119 HaveBroadcasting => 0,
2120 Doc=> <<'EOF',
2121 =for ref
2122  
2123 Seed random-number generator with a 64-bit int. Will generate seed data
2124 for a number of threads equal to the return-value of
2125 L<PDL::Core/online_cpus>.
2126 As of 2.062, the generator changed from Perl's generator to xoshiro256++
2127 (see L<https://prng.di.unimi.it/>).
2128 Before PDL 2.090, this was called C<srand>, but was renamed to avoid
2129 clashing with Perl's built-in.
2130  
2131 =for usage
2132  
2133 srandom(); # uses current time
2134 srandom(5); # fixed number e.g. for testing
2135  
2136 EOF
2137 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
2138 *srandom = \&PDL::srandom;
2139 sub PDL::srandom { PDL::_srandom_int($_[0] // PDL::Core::seed()) }
2140 EOD
2141 );
2142  
2143 pp_def(
2144 'random',
2145 Pars=>'[o] a();',
2146 PMFunc => '',
2147 Code => <<'EOF',
2148 PDL_MAYBE_SRAND
2149 int rand_offset = -1;
2150 broadcastloop %{
2151 PDL_RAND_SET_OFFSET(rand_offset, $PRIV(broadcast), $PDL(a));
2152 $a() = pdl_drand(pdl_rand_state + 4*rand_offset);
2153 %}
2154 EOF
2155 Doc=> <<'EOF',
2156 =for ref
2157  
2158 Constructor which returns ndarray of random numbers, real data-types only.
2159  
2160 =for usage
2161  
2162 $x = random([type], $nx, $ny, $nz,...);
2163 $x = random $y;
2164  
2165 etc (see L<zeroes|PDL::Core/zeroes>).
2166  
2167 This is the uniform distribution between 0 and 1 (assumedly
2168 excluding 1 itself). The arguments are the same as C<zeroes>
2169 (q.v.) - i.e. one can specify dimensions, types or give
2170 a template.
2171  
2172 You can use the PDL function L</srandom> to seed the random generator.
2173 If it has not been called yet, it will be with the current time.
2174 As of 2.062, the generator changed from Perl's generator to xoshiro256++
2175 (see L<https://prng.di.unimi.it/>).
2176 EOF
2177 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
2178 sub random { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->random : PDL->random(@_) }
2179 sub PDL::random {
2180 splice @_, 1, 0, double() if !ref($_[0]) and @_<=1;
2181 my $x = &PDL::Core::_construct;
2182 PDL::_random_int($x);
2183 return $x;
2184 }
2185 EOD
2186 );
2187  
2188 pp_def(
2189 'randsym',
2190 Pars=>'[o] a();',
2191 PMFunc => '',
2192 Code => <<'EOF',
2193 PDL_MAYBE_SRAND
2194 int rand_offset = -1;
2195 broadcastloop %{
2196 PDL_RAND_SET_OFFSET(rand_offset, $PRIV(broadcast), $PDL(a));
2197 long double tmp;
2198 do tmp = pdl_drand(pdl_rand_state + 4*rand_offset); while (tmp == 0.0); /* 0 < tmp < 1 */
2199 $a() = tmp;
2200 %}
2201 EOF
2202 Doc=> <<'EOF',
2203 =for ref
2204  
2205 Constructor which returns ndarray of random numbers, real data-types only.
2206  
2207 =for usage
2208  
2209 $x = randsym([type], $nx, $ny, $nz,...);
2210 $x = randsym $y;
2211  
2212 etc (see L<zeroes|PDL::Core/zeroes>).
2213  
2214 This is the uniform distribution between 0 and 1 (excluding both 0 and
2215 1, cf L</random>). The arguments are the same as C<zeroes> (q.v.) -
2216 i.e. one can specify dimensions, types or give a template.
2217  
2218 You can use the PDL function L</srandom> to seed the random generator.
2219 If it has not been called yet, it will be with the current time.
2220 EOF
2221 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
2222 sub randsym { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->randsym : PDL->randsym(@_) }
2223 sub PDL::randsym {
2224 splice @_, 1, 0, double() if !ref($_[0]) and @_<=1;
2225 my $x = &PDL::Core::_construct;
2226 PDL::_randsym_int($x);
2227 return $x;
2228 }
2229 EOD
2230 );
2231  
2232 pp_add_exported('','grandom');
2233 pp_addpm(<<'EOD');
2234 =head2 grandom
2235  
2236 =for ref
2237  
2238 Constructor which returns ndarray of Gaussian random numbers
2239  
2240 =for usage
2241  
2242 $x = grandom([type], $nx, $ny, $nz,...);
2243 $x = grandom $y;
2244  
2245 etc (see L<zeroes|PDL::Core/zeroes>).
2246  
2247 This is generated using the math library routine C<ndtri>.
2248  
2249 Mean = 0, Stddev = 1
2250  
2251 You can use the PDL function L</srandom> to seed the random generator.
2252 If it has not been called yet, it will be with the current time.
2253  
2254 =cut
2255  
2256 sub grandom { ref($_[0]) && ref($_[0]) ne 'PDL::Type' ? $_[0]->grandom : PDL->grandom(@_) }
2257 sub PDL::grandom {
2258 my $x = &PDL::Core::_construct;
2259 use PDL::Math 'ndtri';
2260 $x .= ndtri(randsym($x));
2261 return $x;
2262 }
2263 EOD
2264  
2265 ###############################################################
2266 # binary searches in an ndarray; various forms
2267 ###############################################################
2268  
2269 # generic front end; defaults to vsearch_sample for backwards compatibility
2270  
2271 pp_add_exported('','vsearch');
2272 pp_addpm(<<'EOD');
2273 =head2 vsearch
2274  
2275 =for sig
2276  
2277 Signature: ( vals(); xs(n); [o] indx(); [\%options] )
2278  
2279 =for ref
2280  
2281 Efficiently search for values in a sorted ndarray, returning indices.
2282  
2283 =for usage
2284  
2285 $idx = vsearch( $vals, $x, [\%options] );
2286 vsearch( $vals, $x, $idx, [\%options ] );
2287  
2288 B<vsearch> performs a binary search in the ordered ndarray C<$x>,
2289 for the values from C<$vals> ndarray, returning indices into C<$x>.
2290 What is a "match", and the meaning of the returned indices, are determined
2291 by the options.
2292  
2293 The C<mode> option indicates which method of searching to use, and may
2294 be one of:
2295  
2296 =over
2297  
2298 =item C<sample>
2299  
2300 invoke L<B<vsearch_sample>|/vsearch_sample>, returning indices appropriate for sampling
2301 within a distribution.
2302  
2303 =item C<insert_leftmost>
2304  
2305 invoke L<B<vsearch_insert_leftmost>|/vsearch_insert_leftmost>, returning the left-most possible
2306 insertion point which still leaves the ndarray sorted.
2307  
2308 =item C<insert_rightmost>
2309  
2310 invoke L<B<vsearch_insert_rightmost>|/vsearch_insert_rightmost>, returning the right-most possible
2311 insertion point which still leaves the ndarray sorted.
2312  
2313 =item C<match>
2314  
2315 invoke L<B<vsearch_match>|/vsearch_match>, returning the index of a matching element,
2316 else -(insertion point + 1)
2317  
2318 =item C<bin_inclusive>
2319  
2320 invoke L<B<vsearch_bin_inclusive>|/vsearch_bin_inclusive>, returning an index appropriate for binning
2321 on a grid where the left bin edges are I<inclusive> of the bin. See
2322 below for further explanation of the bin.
2323  
2324 =item C<bin_exclusive>
2325  
2326 invoke L<B<vsearch_bin_exclusive>|/vsearch_bin_exclusive>, returning an index appropriate for binning
2327 on a grid where the left bin edges are I<exclusive> of the bin. See
2328 below for further explanation of the bin.
2329  
2330 =back
2331  
2332 The default value of C<mode> is C<sample>.
2333  
2334 =for example
2335  
2336 use PDL;
2337  
2338 my @modes = qw( sample insert_leftmost insert_rightmost match
2339 bin_inclusive bin_exclusive );
2340  
2341 # Generate a sequence of 3 zeros, 3 ones, ..., 3 fours.
2342 my $x = zeroes(3,5)->yvals->flat;
2343  
2344 for my $mode ( @modes ) {
2345 # if the value is in $x
2346 my $contained = 2;
2347 my $idx_contained = vsearch( $contained, $x, { mode => $mode } );
2348 my $x_contained = $x->copy;
2349 $x_contained->slice( $idx_contained ) .= 9;
2350  
2351 # if the value is not in $x
2352 my $not_contained = 1.5;
2353 my $idx_not_contained = vsearch( $not_contained, $x, { mode => $mode } );
2354 my $x_not_contained = $x->copy;
2355 $x_not_contained->slice( $idx_not_contained ) .= 9;
2356  
2357 print sprintf("%-23s%30s\n", '$x', $x);
2358 print sprintf("%-23s%30s\n", "$mode ($contained)", $x_contained);
2359 print sprintf("%-23s%30s\n\n", "$mode ($not_contained)", $x_not_contained);
2360 }
2361  
2362 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2363 # sample (2) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
2364 # sample (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
2365 #
2366 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2367 # insert_leftmost (2) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
2368 # insert_leftmost (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
2369 #
2370 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2371 # insert_rightmost (2) [0 0 0 1 1 1 2 2 2 9 3 3 4 4 4]
2372 # insert_rightmost (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
2373 #
2374 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2375 # match (2) [0 0 0 1 1 1 2 9 2 3 3 3 4 4 4]
2376 # match (1.5) [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
2377 #
2378 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2379 # bin_inclusive (2) [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
2380 # bin_inclusive (1.5) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
2381 #
2382 # $x [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
2383 # bin_exclusive (2) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
2384 # bin_exclusive (1.5) [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
2385  
2386  
2387 Also see
2388 L<B<vsearch_sample>|/vsearch_sample>,
2389 L<B<vsearch_insert_leftmost>|/vsearch_insert_leftmost>,
2390 L<B<vsearch_insert_rightmost>|/vsearch_insert_rightmost>,
2391 L<B<vsearch_match>|/vsearch_match>,
2392 L<B<vsearch_bin_inclusive>|/vsearch_bin_inclusive>, and
2393 L<B<vsearch_bin_exclusive>|/vsearch_bin_exclusive>
2394  
2395 =cut
2396  
2397 sub vsearch {
2398 my $opt = 'HASH' eq ref $_[-1]
2399 ? pop
2400 : { mode => 'sample' };
2401  
2402 croak( "unknown options to vsearch\n" )
2403 if ( ! defined $opt->{mode} && keys %$opt )
2404 || keys %$opt > 1;
2405  
2406 my $mode = $opt->{mode};
2407 goto
2408 $mode eq 'sample' ? \&vsearch_sample
2409 : $mode eq 'insert_leftmost' ? \&vsearch_insert_leftmost
2410 : $mode eq 'insert_rightmost' ? \&vsearch_insert_rightmost
2411 : $mode eq 'match' ? \&vsearch_match
2412 : $mode eq 'bin_inclusive' ? \&vsearch_bin_inclusive
2413 : $mode eq 'bin_exclusive' ? \&vsearch_bin_exclusive
2414 : croak( "unknown vsearch mode: $mode\n" );
2415 }
2416  
2417 *PDL::vsearch = \&vsearch;
2418  
2419 EOD
2420  
2421 use Text::Tabs qw[ expand ];
2422 sub undent {
2423 my $txt = expand( shift );
2424  
2425 $txt =~ s/^([ \t]+)-{4}.*$//m;
2426 $txt =~ s/^$1//mg
2427 if defined $1;
2428 $txt;
2429 }
2430  
2431 for my $func ( [
2432 vsearch_sample => {
2433 low => -1,
2434 high => '$SIZE(n)',
2435 up => '($x(n => n1) > $x(n => 0))',
2436 code => q[
2437 while ( high - low > 1 ) {
2438 mid = %MID%;
2439 if ( ( value > $x(n => mid ) ) == up ) low = mid;
2440 else high = mid;
2441 }
2442 $idx() = low >= n1 ? n1
2443 : up ? low + 1
2444 : PDLMAX(low, 0);
2445 ----
2446 ],
2447 ref =>
2448 'Search for values in a sorted array, return index appropriate for sampling from a distribution',
2449  
2450 doc_pre => q[
2451 B<%FUNC%> returns an index I<I> for each value I<V> of C<$vals> appropriate
2452 for sampling C<$vals>
2453 ----
2454 ],
2455 doc_incr => q[
2456 V <= x[0] : I = 0
2457 x[0] < V <= x[-1] : I s.t. x[I-1] < V <= x[I]
2458 x[-1] < V : I = $x->nelem -1
2459 ----
2460 ],
2461  
2462 doc_decr => q[
2463 V > x[0] : I = 0
2464 x[0] >= V > x[-1] : I s.t. x[I] >= V > x[I+1]
2465 x[-1] >= V : I = $x->nelem - 1
2466 ----
2467 ],
2468  
2469 doc_post => q[
2470 If all elements of C<$x> are equal, I<< I = $x->nelem - 1 >>.
2471  
2472 If C<$x> contains duplicated elements, I<I> is the index of the
2473 leftmost (by position in array) duplicate if I<V> matches.
2474  
2475 =for example
2476  
2477 This function is useful e.g. when you have a list of probabilities
2478 for events and want to generate indices to events:
2479  
2480 $x = pdl(.01,.86,.93,1); # Barnsley IFS probabilities cumulatively
2481 $y = random 20;
2482 $c = %FUNC%($y, $x); # Now, $c will have the appropriate distr.
2483  
2484 It is possible to use the L<cumusumover|PDL::Ufunc/cumusumover>
2485 function to obtain cumulative probabilities from absolute probabilities.
2486 ----
2487 ],
2488  
2489 },
2490 ],
2491  
2492 [
2493 # return left-most possible insertion point.
2494 # lowest index where x[i] >= value
2495 vsearch_insert_leftmost => {
2496 low => 0,
2497 high => 'n1',
2498 code => q[
2499 while (low <= high ) {
2500 mid = %MID%;
2501 if ( ( $x(n => mid) >= value ) == up ) high = mid - 1;
2502 else low = mid + 1;
2503 }
2504 $idx() = up ? low : high;
2505 ],
2506 ref =>
2507 'Determine the insertion point for values in a sorted array, inserting before duplicates.',
2508  
2509 doc_pre => q[
2510 B<%FUNC%> returns an index I<I> for each value I<V> of
2511 C<$vals> equal to the leftmost position (by index in array) within
2512 C<$x> that I<V> may be inserted and still maintain the order in
2513 C<$x>.
2514  
2515 Insertion at index I<I> involves shifting elements I<I> and higher of
2516 C<$x> to the right by one and setting the now empty element at index
2517 I<I> to I<V>.
2518 ----
2519 ],
2520 doc_incr => q[
2521 V <= x[0] : I = 0
2522 x[0] < V <= x[-1] : I s.t. x[I-1] < V <= x[I]
2523 x[-1] < V : I = $x->nelem
2524 ----
2525 ],
2526  
2527 doc_decr => q[
2528 V > x[0] : I = -1
2529 x[0] >= V >= x[-1] : I s.t. x[I] >= V > x[I+1]
2530 x[-1] >= V : I = $x->nelem -1
2531 ----
2532 ],
2533  
2534 doc_post => q[
2535 If all elements of C<$x> are equal,
2536  
2537 i = 0
2538  
2539 If C<$x> contains duplicated elements, I<I> is the index of the
2540 leftmost (by index in array) duplicate if I<V> matches.
2541 ----
2542 ],
2543  
2544 },
2545 ],
2546  
2547 [
2548 # return right-most possible insertion point.
2549 # lowest index where x[i] > value
2550 vsearch_insert_rightmost => {
2551 low => 0,
2552 high => 'n1',
2553 code => q[
2554 while (low <= high ) {
2555 mid = %MID%;
2556 if ( ( $x(n => mid) > value ) == up ) high = mid - 1;
2557 else low = mid + 1;
2558 }
2559 $idx() = up ? low : high;
2560 ],
2561 ref =>
2562 'Determine the insertion point for values in a sorted array, inserting after duplicates.',
2563  
2564 doc_pre => q[
2565 B<%FUNC%> returns an index I<I> for each value I<V> of
2566 C<$vals> equal to the rightmost position (by index in array) within
2567 C<$x> that I<V> may be inserted and still maintain the order in
2568 C<$x>.
2569  
2570 Insertion at index I<I> involves shifting elements I<I> and higher of
2571 C<$x> to the right by one and setting the now empty element at index
2572 I<I> to I<V>.
2573 ----
2574 ],
2575 doc_incr => q[
2576 V < x[0] : I = 0
2577 x[0] <= V < x[-1] : I s.t. x[I-1] <= V < x[I]
2578 x[-1] <= V : I = $x->nelem
2579 ----
2580 ],
2581  
2582 doc_decr => q[
2583 V >= x[0] : I = -1
2584 x[0] > V >= x[-1] : I s.t. x[I] >= V > x[I+1]
2585 x[-1] > V : I = $x->nelem -1
2586 ----
2587 ],
2588  
2589 doc_post => q[
2590 If all elements of C<$x> are equal,
2591  
2592 i = $x->nelem - 1
2593  
2594 If C<$x> contains duplicated elements, I<I> is the index of the
2595 leftmost (by index in array) duplicate if I<V> matches.
2596 ----
2597 ],
2598  
2599 },
2600  
2601 ],
2602 [
2603 # return index of matching element, else -( insertion point + 1 )
2604 # patterned after the Java binarySearch interface; see
2605 # http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
2606 vsearch_match => {
2607 low => 0,
2608 high => 'n1',
2609 code => q[
2610 int done = 0;
2611  
2612 while (low <= high ) {
2613 $GENERIC() mid_value;
2614  
2615 mid = %MID%;
2616  
2617 mid_value = $x(n=>mid);
2618  
2619 if ( up ) {
2620 if ( mid_value > value ) { high = mid - 1; }
2621 else if ( mid_value < value ) { low = mid + 1; }
2622 else { done = 1; break; }
2623 }
2624 else {
2625 if ( mid_value < value ) { high = mid - 1; }
2626 else if ( mid_value > value ) { low = mid + 1; }
2627 else { done = 1; break; }
2628 }
2629 }
2630 $idx() = done ? mid
2631 : up ? - ( low + 1 )
2632 : - ( high + 1 );
2633 ],
2634 ref => 'Match values against a sorted array.',
2635  
2636 doc_pre => q[
2637 B<%FUNC%> returns an index I<I> for each value I<V> of
2638 C<$vals>. If I<V> matches an element in C<$x>, I<I> is the
2639 index of that element, otherwise it is I<-( insertion_point + 1 )>,
2640 where I<insertion_point> is an index in C<$x> where I<V> may be
2641 inserted while maintaining the order in C<$x>. If C<$x> has
2642 duplicated values, I<I> may refer to any of them.
2643 ----
2644 ],
2645  
2646 },
2647 ],
2648 [
2649 # x[i] is the INclusive left edge of the bin
2650 # return i, s.t. x[i] <= value < x[i+1].
2651 # returns -1 if x[0] > value
2652 # returns N-1 if x[-1] <= value
2653 vsearch_bin_inclusive => {
2654 low => 0,
2655 high => 'n1',
2656 code => q[
2657 while (low <= high ) {
2658 mid = %MID%;
2659 if ( ( $x(n => mid) <= value ) == up ) low = mid + 1;
2660 else high = mid - 1;
2661 }
2662 $idx() = up ? high: low;
2663 ],
2664 ref =>
2665 'Determine the index for values in a sorted array of bins, lower bound inclusive.',
2666  
2667 doc_pre => q[
2668 C<$x> represents the edges of contiguous bins, with the first and
2669 last elements representing the outer edges of the outer bins, and the
2670 inner elements the shared bin edges.
2671  
2672 The lower bound of a bin is inclusive to the bin, its outer bound is exclusive to it.
2673 B<%FUNC%> returns an index I<I> for each value I<V> of C<$vals>
2674 ----
2675 ],
2676 doc_incr => q[
2677 V < x[0] : I = -1
2678 x[0] <= V < x[-1] : I s.t. x[I] <= V < x[I+1]
2679 x[-1] <= V : I = $x->nelem - 1
2680 ----
2681 ],
2682  
2683 doc_decr => q[
2684 V >= x[0] : I = 0
2685 x[0] > V >= x[-1] : I s.t. x[I+1] > V >= x[I]
2686 x[-1] > V : I = $x->nelem
2687 ----
2688 ],
2689  
2690 doc_post => q[
2691 If all elements of C<$x> are equal,
2692  
2693 i = $x->nelem - 1
2694  
2695 If C<$x> contains duplicated elements, I<I> is the index of the
2696 righmost (by index in array) duplicate if I<V> matches.
2697 ----
2698 ],
2699  
2700 },
2701 ],
2702  
2703 [
2704 # x[i] is the EXclusive left edge of the bin
2705 # return i, s.t. x[i] < value <= x[i+1].
2706 # returns -1 if x[0] >= value
2707 # returns N-1 if x[-1] < value
2708 vsearch_bin_exclusive => {
2709 low => 0,
2710 high => 'n1',
2711 code => q[
2712 while (low <= high ) {
2713 mid = %MID%;
2714 if ( ( $x(n => mid) < value ) == up ) low = mid + 1;
2715 else high = mid - 1;
2716 }
2717 $idx() = up ? high: low;
2718 ],
2719 ref =>
2720 'Determine the index for values in a sorted array of bins, lower bound exclusive.',
2721  
2722 doc_pre => q[
2723 C<$x> represents the edges of contiguous bins, with the first and
2724 last elements representing the outer edges of the outer bins, and the
2725 inner elements the shared bin edges.
2726  
2727 The lower bound of a bin is exclusive to the bin, its upper bound is inclusive to it.
2728 B<%FUNC%> returns an index I<I> for each value I<V> of C<$vals>.
2729 ----
2730 ],
2731 doc_incr => q[
2732 V <= x[0] : I = -1
2733 x[0] < V <= x[-1] : I s.t. x[I] < V <= x[I+1]
2734 x[-1] < V : I = $x->nelem - 1
2735 ----
2736 ],
2737  
2738 doc_decr => q[
2739 V > x[0] : I = 0
2740 x[0] >= V > x[-1] : I s.t. x[I-1] >= V > x[I]
2741 x[-1] >= V : I = $x->nelem
2742 ----
2743 ],
2744  
2745 doc_post => q[
2746 If all elements of C<$x> are equal,
2747  
2748 i = $x->nelem - 1
2749  
2750 If C<$x> contains duplicated elements, I<I> is the index of the
2751 righmost (by index in array) duplicate if I<V> matches.
2752 ----
2753 ],
2754  
2755 }
2756 ],
2757  
2758 )
2759  
2760 {
2761 my ( $func, $algo ) = @$func;
2762  
2763 my %replace = (
2764 # calculate midpoint of range; ensure we don't overflow
2765 # (low+high)>>1 for large values of low + high
2766 # see sf.net bug #360
2767 '%MID%' => 'low + (( high - low )>> 1);',
2768  
2769 # determine which way the data are sorted. vsearch_sample
2770 # overrides this.
2771 '%UP%' => '$x(n => n1) >= $x(n => 0)',
2772  
2773 '%FUNC%' => $func,
2774  
2775 '%PRE%' => undent(
2776 q[
2777 %DOC_PRE%
2778 ----
2779 ]
2780 ),
2781  
2782  
2783  
2784 '%BODY%' => undent(
2785 q[
2786 I<I> has the following properties:
2787  
2788 =over
2789  
2790 =item *
2791  
2792 if C<$x> is sorted in increasing order
2793  
2794 %DOC_INCR%
2795  
2796 =item *
2797  
2798 if C<$x> is sorted in decreasing order
2799  
2800 %DOC_DECR%
2801  
2802 =back
2803 ----
2804 ]
2805 ),
2806  
2807 '%POST%' => undent(
2808 q[
2809 %DOC_POST%
2810 ----
2811 ]
2812 ),
2813  
2814 map { ( "%\U$_%" => undent( $algo->{$_} ) ) } keys %$algo,
2815 );
2816  
2817 $replace{'%PRE%'} = '' unless defined $replace{'%DOC_PRE%'};
2818 $replace{'%BODY%'} = ''
2819 unless defined $replace{'%DOC_INCR%'} || defined $replace{'%DOC_DECR%'};
2820 $replace{'%POST%'} = '' unless defined $replace{'%DOC_POST%'};
2821  
2822  
2823 my $code = undent q[
2824 loop(n) %{
2825 if ( $ISGOOD(vals()) ) {
2826 PDL_Indx n1 = $SIZE(n)-1;
2827 PDL_Indx low = %LOW%;
2828 PDL_Indx high = %HIGH%;
2829 PDL_Indx mid;
2830  
2831 $GENERIC() value = $vals();
2832  
2833 /* determine sort order of data */
2834 int up = %UP%;
2835 %CODE%
2836 }
2837  
2838 else {
2839 $SETBAD(idx());
2840 }
2841 %}
2842 ----
2843 ];
2844  
2845 my $doc = undent q[
2846 =for ref
2847  
2848 %REF%
2849  
2850 =for usage
2851  
2852 $idx = %FUNC%($vals, $x);
2853  
2854 C<$x> must be sorted, but may be in decreasing or increasing
2855 order. if C<$x> is empty, then all values in C<$idx> will be
2856 set to the bad value.
2857  
2858 %PRE%
2859 %BODY%
2860 %POST%
2861 ----
2862 ];
2863  
2864  
2865 # redo until nothing changes
2866 for my $tref ( \$code, \$doc ) {
2867 1 while $$tref =~ s/(%[\w_]+%)/$replace{$1}/ge;
2868 }
2869  
2870 pp_def(
2871 $func,
2872 HandleBad => 1,
2873 BadDoc => 'bad values in vals() result in bad values in idx()',
2874 Pars => 'vals(); x(n); indx [o]idx()',
2875 GenericTypes => $F, # too restrictive ?
2876 Code => $code,
2877 Doc => $doc,
2878 );
2879 }
2880  
2881 ###############################################################
2882 # routines somehow related to interpolation
2883 ###############################################################
2884  
2885 pp_def('interpolate',
2886 HandleBad => 0,
2887 BadDoc => 'needs major (?) work to handles bad values',
2888 Pars => '!complex xi(); !complex x(n); y(n); [o] yi(); int [o] err()',
2889 GenericTypes => $AF,
2890 Code => pp_line_numbers(__LINE__, <<'EOF'),
2891 PDL_Indx n = $SIZE(n), n1 = n-1;
2892 broadcastloop %{
2893 PDL_Indx jl = -1, jh = n;
2894 int carp = 0, up = ($x(n => n1) > $x(n => 0));
2895 while (jh-jl > 1) { /* binary search */
2896 PDL_Indx m = (jh+jl) >> 1;
2897 if (($xi() > $x(n => m)) == up)
2898 jl = m;
2899 else
2900 jh = m;
2901 }
2902 if (jl == -1) {
2903 if ($xi() != $x(n => 0)) carp = 1;
2904 jl = 0;
2905 } else if (jh == n) {
2906 if ($xi() != $x(n => n1)) carp = 1;
2907 jl = n1-1;
2908 }
2909 jh = jl+1;
2910 $GENERIC() d = $x(n=>jh) - $x(n=>jl);
2911 if (d == 0) $CROAK("identical abscissas");
2912 d = ($x(n=>jh) - $xi())/d;
2913 $yi() = d*$y(n => jl) + (1-d)*$y(n => jh);
2914 $err() = carp;
2915 %}
2916 EOF
2917 Doc => <<'EOD',
2918 =for ref
2919  
2920 routine for 1D linear interpolation
2921  
2922 Given a set of points C<($x,$y)>, use linear interpolation
2923 to find the values C<$yi> at a set of points C<$xi>.
2924  
2925 C<interpolate> uses a binary search to find the suspects, er...,
2926 interpolation indices and therefore abscissas (ie C<$x>)
2927 have to be I<strictly> ordered (increasing or decreasing).
2928 For interpolation at lots of
2929 closely spaced abscissas an approach that uses the last index found as
2930 a start for the next search can be faster (compare Numerical Recipes
2931 C<hunt> routine). Feel free to implement that on top of the binary
2932 search if you like. For out of bounds values it just does a linear
2933 extrapolation and sets the corresponding element of C<$err> to 1,
2934 which is otherwise 0.
2935  
2936 See also L</interpol>, which uses the same routine,
2937 differing only in the handling of extrapolation - an error message
2938 is printed rather than returning an error ndarray.
2939  
2940 Note that C<interpolate> can use complex values for C<$y> and C<$yi> but
2941 C<$x> and C<$xi> must be real.
2942 EOD
2943 );
2944  
2945 pp_add_exported('', 'interpol');
2946 pp_addpm(<<'EOD');
2947 =head2 interpol
2948  
2949 =for sig
2950  
2951 Signature: (xi(); x(n); y(n); [o] yi())
2952  
2953 =for ref
2954  
2955 routine for 1D linear interpolation
2956  
2957 =for usage
2958  
2959 $yi = interpol($xi, $x, $y)
2960  
2961 C<interpol> uses the same search method as L</interpolate>,
2962 hence C<$x> must be I<strictly> ordered (either increasing or decreasing).
2963 The difference occurs in the handling of out-of-bounds values; here
2964 an error message is printed.
2965  
2966 =cut
2967  
2968 # kept in for backwards compatibility
2969 sub interpol ($$$;$) {
2970 my $xi = shift;
2971 my $x = shift;
2972 my $y = shift;
2973 my $yi = @_ == 1 ? $_[0] : PDL->null;
2974 interpolate( $xi, $x, $y, $yi, my $err = PDL->null );
2975 print "some values had to be extrapolated\n"
2976 if any $err;
2977 return $yi if @_ == 0;
2978 } # sub: interpol()
2979 *PDL::interpol = \&interpol;
2980  
2981 EOD
2982  
2983 pp_add_exported('','interpND');
2984 pp_addpm(<<'EOD');
2985 =head2 interpND
2986  
2987 =for ref
2988  
2989 Interpolate values from an N-D ndarray, with switchable method
2990  
2991 =for example
2992  
2993 $source = 10*xvals(10,10) + yvals(10,10);
2994 $index = pdl([[2.2,3.5],[4.1,5.0]],[[6.0,7.4],[8,9]]);
2995 print $source->interpND( $index );
2996  
2997 InterpND acts like L<indexND|PDL::Slices/indexND>,
2998 collapsing C<$index> by lookup
2999 into C<$source>; but it does interpolation rather than direct sampling.
3000 The interpolation method and boundary condition are switchable via
3001 an options hash.
3002  
3003 By default, linear or sample interpolation is used, with constant
3004 value outside the boundaries of the source pdl. No dataflow occurs,
3005 because in general the output is computed rather than indexed.
3006  
3007 All the interpolation methods treat the pixels as value-centered, so
3008 the C<sample> method will return C<< $a->(0) >> for coordinate values on
3009 the set [-0.5,0.5], and all methods will return C<< $a->(1) >> for
3010 a coordinate value of exactly 1.
3011  
3012 Recognized options:
3013  
3014 =over 3
3015  
3016 =item method
3017  
3018 Values can be:
3019  
3020 =over 3
3021  
3022 =item * 0, s, sample, Sample (default for integer source types)
3023  
3024 The nearest value is taken. Pixels are regarded as centered on their
3025 respective integer coordinates (no offset from the linear case).
3026  
3027 =item * 1, l, linear, Linear (default for floating point source types)
3028  
3029 The values are N-linearly interpolated from an N-dimensional cube of size 2.
3030  
3031 =item * 3, c, cube, cubic, Cubic
3032  
3033 The values are interpolated using a local cubic fit to the data. The
3034 fit is constrained to match the original data and its derivative at the
3035 data points. The second derivative of the fit is not continuous at the
3036 data points. Multidimensional datasets are interpolated by the
3037 successive-collapse method.
3038  
3039 (Note that the constraint on the first derivative causes a small amount
3040 of ringing around sudden features such as step functions).
3041  
3042 =item * f, fft, fourier, Fourier
3043  
3044 The source is Fourier transformed, and the interpolated values are
3045 explicitly calculated from the coefficients. The boundary condition
3046 option is ignored -- periodic boundaries are imposed.
3047  
3048 If you pass in the option "fft", and it is a list (ARRAY) ref, then it
3049 is a stash for the magnitude and phase of the source FFT. If the list
3050 has two elements then they are taken as already computed; otherwise
3051 they are calculated and put in the stash.
3052  
3053 =back
3054  
3055 =item b, bound, boundary, Boundary
3056  
3057 This option is passed unmodified into L<indexND|PDL::Slices/indexND>,
3058 which is used as the indexing engine for the interpolation.
3059 Some current allowed values are 'extend', 'periodic', 'truncate', and 'mirror'
3060 (default is 'truncate').
3061  
3062 =item bad
3063  
3064 contains the fill value used for 'truncate' boundary. (default 0)
3065  
3066 =item fft
3067  
3068 An array ref whose associated list is used to stash the FFT of the source
3069 data, for the FFT method.
3070  
3071 =back
3072  
3073 =cut
3074  
3075 *interpND = *PDL::interpND;
3076 sub PDL::interpND {
3077 my $source = shift;
3078 my $index = shift;
3079 my $options = shift;
3080  
3081 barf 'Usage: interpND($source,$index[,{%options}])'
3082 if defined $options and ref $options ne 'HASH';
3083  
3084 my $opt = defined $options ? $options : {};
3085  
3086 my $method = $opt->{m} || $opt->{meth} || $opt->{method} || $opt->{Method};
3087 $method //= $source->type->integer ? 'sample' : 'linear';
3088  
3089 my $boundary = $opt->{b} || $opt->{boundary} || $opt->{Boundary} || $opt->{bound} || $opt->{Bound} || 'extend';
3090 my $bad = $opt->{bad} || $opt->{Bad} || 0.0;
3091  
3092 return $source->range(PDL::Math::floor($index+0.5),0,$boundary)
3093 if $method =~ m/^s(am(p(le)?)?)?/i;
3094  
3095 if (($method eq 1) || $method =~ m/^l(in(ear)?)?/i) {
3096 ## key: (ith = index broadcast; cth = cube broadcast; sth = source broadcast)
3097 my $d = $index->dim(0);
3098 my $di = $index->ndims - 1;
3099  
3100 # Grab a 2-on-a-side n-cube around each desired pixel
3101 my $samp = $source->range($index->floor,2,$boundary); # (ith, cth, sth)
3102  
3103 # Reorder to put the cube dimensions in front and convert to a list
3104 $samp = $samp->reorder( $di .. $di+$d-1,
3105 0 .. $di-1,
3106 $di+$d .. $samp->ndims-1) # (cth, ith, sth)
3107 ->clump($d); # (clst, ith, sth)
3108  
3109 # Enumerate the corners of an n-cube and convert to a list
3110 # (the 'x' is the normal perl repeat operator)
3111 my $crnr = PDL::Basic::ndcoords( (2) x $index->dim(0) ) # (index,cth)
3112 ->mv(0,-1)->clump($index->dim(0))->mv(-1,0); # (index, clst)
3113 # a & b are the weighting coefficients.
3114 my($x,$y);
3115 $index->where( 0 * $index ) .= -10; # Change NaN to invalid
3116 {
3117 my $bb = PDL::Math::floor($index);
3118 $x = ($index - $bb) -> dummy(1,$crnr->dim(1)); # index, clst, ith
3119 $y = ($bb + 1 - $index) -> dummy(1,$crnr->dim(1)); # index, clst, ith
3120 }
3121  
3122 # Use 1/0 corners to select which multiplier happens, multiply
3123 # 'em all together to get sample weights, and sum to get the answer.
3124 my $out0 = ( ($x * ($crnr==1) + $y * ($crnr==0)) #index, clst, ith
3125 -> prodover #clst, ith
3126 );
3127  
3128 my $out = ($out0 * $samp)->sumover; # ith, sth
3129  
3130 # Work around BAD-not-being-contagious bug in PDL <= 2.6 bad handling code --CED 3-April-2013
3131 if ($source->badflag) {
3132 my $baddies = $samp->isbad->orover;
3133 $out = $out->setbadif($baddies);
3134 }
3135  
3136 $out = $out->convert($source->type->enum) if $out->type != $source->type;
3137 return $out;
3138  
3139 } elsif(($method eq 3) || $method =~ m/^c(u(b(e|ic)?)?)?/i) {
3140  
3141 my ($d,@di) = $index->dims;
3142 my $di = $index->ndims - 1;
3143  
3144 # Grab a 4-on-a-side n-cube around each desired pixel
3145 my $samp = $source->range($index->floor - 1,4,$boundary) #ith, cth, sth
3146 ->reorder( $di .. $di+$d-1, 0..$di-1, $di+$d .. $source->ndims-1 );
3147 # (cth, ith, sth)
3148  
3149 # Make a cube of the subpixel offsets, and expand its dims to
3150 # a 4-on-a-side N-1 cube, to match the slices of $samp (used below).
3151 my $y = $index - $index->floor;
3152 for my $i(1..$d-1) {
3153 $y = $y->dummy($i,4);
3154 }
3155  
3156 # Collapse by interpolation, one dimension at a time...
3157 for my $i(0..$d-1) {
3158 my $a0 = $samp->slice("(1)"); # Just-under-sample
3159 my $a1 = $samp->slice("(2)"); # Just-over-sample
3160 my $a1a0 = $a1 - $a0;
3161  
3162 my $gradient = 0.5 * ($samp->slice("2:3")-$samp->slice("0:1"));
3163 my $s0 = $gradient->slice("(0)"); # Just-under-gradient
3164 my $s1 = $gradient->slice("(1)"); # Just-over-gradient
3165  
3166 my $bb = $y->slice("($i)");
3167  
3168 # Collapse the sample...
3169 $samp = ( $a0 +
3170 $bb * (
3171 $s0 +
3172 $bb * ( (3 * $a1a0 - 2*$s0 - $s1) +
3173 $bb * ( $s1 + $s0 - 2*$a1a0 )
3174 )
3175 )
3176 );
3177  
3178 # "Collapse" the subpixel offset...
3179 $y = $y->slice(":,($i)");
3180 }
3181  
3182 $samp = $samp->convert($source->type->enum) if $samp->type != $source->type;
3183 return $samp;
3184  
3185 } elsif($method =~ m/^f(ft|ourier)?/i) {
3186  
3187 require PDL::FFT;
3188 my $fftref = $opt->{fft};
3189 $fftref = [] unless(ref $fftref eq 'ARRAY');
3190 if(@$fftref != 2) {
3191 my $x = $source->copy;
3192 my $y = zeroes($source);
3193 PDL::FFT::fftnd($x,$y);
3194 $fftref->[0] = sqrt($x*$x+$y*$y) / $x->nelem;
3195 $fftref->[1] = - atan2($y,$x);
3196 }
3197  
3198 my $i;
3199 my $c = PDL::Basic::ndcoords($source); # (dim, source-dims)
3200 for $i(1..$index->ndims-1) {
3201 $c = $c->dummy($i,$index->dim($i))
3202 }
3203 my $id = $index->ndims-1;
3204 my $phase = (($c * $index * 3.14159 * 2 / pdl($source->dims))
3205 ->sumover) # (index-dims, source-dims)
3206 ->reorder($id..$id+$source->ndims-1,0..$id-1); # (src, index)
3207  
3208 my $phref = $fftref->[1]->copy; # (source-dims)
3209 my $mag = $fftref->[0]->copy; # (source-dims)
3210  
3211 for $i(1..$index->ndims-1) {
3212 $phref = $phref->dummy(-1,$index->dim($i));
3213 $mag = $mag->dummy(-1,$index->dim($i));
3214 }
3215 my $out = cos($phase + $phref ) * $mag;
3216 $out = $out->clump($source->ndims)->sumover;
3217 $out = $out->convert($source->type->enum) if $out->type != $source->type;
3218 return $out;
3219 } else {
3220 barf("interpND: unknown method '$method'; valid ones are 'linear' and 'sample'.\n");
3221 }
3222 }
3223  
3224 EOD
3225  
3226 ##############################################################
3227 # things related to indexing: one2nd, which, where
3228 ##############################################################
3229  
3230 pp_add_exported("", 'one2nd');
3231 pp_addpm(<<'EOD');
3232 =head2 one2nd
3233  
3234 =for ref
3235  
3236 Converts a one dimensional index ndarray to a set of ND coordinates
3237  
3238 =for usage
3239  
3240 @coords=one2nd($x, $indices)
3241  
3242 returns an array of ndarrays containing the ND indexes corresponding to
3243 the one dimensional list indices. The indices are assumed to
3244 correspond to array C<$x> clumped using C<clump(-1)>. This routine is
3245 used in the old vector form of L</whichND>, but is useful on
3246 its own occasionally.
3247  
3248 Returned ndarrays have the L<indx|PDL::Core/indx> datatype. C<$indices> can have
3249 values larger than C<< $x->nelem >> but negative values in C<$indices>
3250 will not give the answer you expect.
3251  
3252 =for example
3253  
3254 pdl> $x=pdl [[[1,2],[-1,1]], [[0,-3],[3,2]]]; $c=$x->clump(-1)
3255 pdl> $maxind=maximum_ind($c); p $maxind;
3256 6
3257 pdl> print one2nd($x, maximum_ind($c))
3258 0 1 1
3259 pdl> p $x->at(0,1,1)
3260 3
3261  
3262 =cut
3263  
3264 *one2nd = \&PDL::one2nd;
3265 sub PDL::one2nd {
3266 barf "Usage: one2nd \$array, \$indices\n" if @_ != 2;
3267 my ($x, $ind)=@_;
3268 my @dimension=$x->dims;
3269 $ind = indx($ind);
3270 my(@index);
3271 my $count=0;
3272 foreach (@dimension) {
3273 $index[$count++]=$ind % $_;
3274 $ind /= $_;
3275 }
3276 return @index;
3277 }
3278  
3279 EOD
3280  
3281 my $doc_which = <<'EOD';
3282  
3283 =for ref
3284  
3285 Returns indices of non-zero values from a 1-D PDL
3286  
3287 =for usage
3288  
3289 $i = which($mask);
3290  
3291 returns a pdl with indices for all those elements that are nonzero in
3292 the mask. Note that the returned indices will be 1D. If you feed in a
3293 multidimensional mask, it will be flattened before the indices are
3294 calculated. See also L</whichND> for multidimensional masks.
3295  
3296 If you want to index into the original mask or a similar ndarray
3297 with output from C<which>, remember to flatten it before calling index:
3298  
3299 $data = random 5, 5;
3300 $idx = which $data > 0.5; # $idx is now 1D
3301 $bigsum = $data->flat->index($idx)->sum; # flatten before indexing
3302  
3303 Compare also L</where> for similar functionality.
3304  
3305 SEE ALSO:
3306  
3307 L</which_both> returns separately the indices of both nonzero and zero
3308 values in the mask.
3309  
3310 L</where_both> returns separately slices of both nonzero and zero
3311 values in the mask.
3312  
3313 L</where> returns associated values from a data PDL, rather than
3314 indices into the mask PDL.
3315  
3316 L</whichND> returns N-D indices into a multidimensional PDL.
3317  
3318 =for example
3319  
3320 pdl> $x = sequence(10); p $x
3321 [0 1 2 3 4 5 6 7 8 9]
3322 pdl> $indx = which($x>6); p $indx
3323 [7 8 9]
3324  
3325 =cut
3326  
3327 EOD
3328  
3329 my $doc_which_both = <<'EOD';
3330  
3331 =for ref
3332  
3333 Returns indices of nonzero and zero values in a mask PDL
3334  
3335 =for usage
3336  
3337 ($i, $c_i) = which_both($mask);
3338  
3339 This works just as L</which>, but the complement of C<$i> will be in
3340 C<$c_i>.
3341  
3342 =for example
3343  
3344 pdl> p $x = sequence(10)
3345 [0 1 2 3 4 5 6 7 8 9]
3346 pdl> ($big, $small) = which_both($x >= 5); p "$big\n$small"
3347 [5 6 7 8 9]
3348 [0 1 2 3 4]
3349  
3350 See also L</whichND_both> for the n-dimensional version.
3351  
3352 =cut
3353  
3354 EOD
3355  
3356 for (
3357 {Name=>'which',
3358 Pars => 'mask(n); indx [o] inds(n); indx [o]lastout()',
3359 Variables => 'PDL_Indx dm=0;',
3360 Elseclause => "",
3361 Outclause => '$lastout() = dm; loop(n=dm) %{ $inds() = -1; %}',
3362 Doc => $doc_which,
3363 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
3364 sub which { my ($this,$out) = @_;
3365 $this = $this->flat;
3366 $out //= $this->nullcreate;
3367 PDL::_which_int($this,$out,my $lastout = $this->nullcreate);
3368 my $lastoutmax = $lastout->max->sclr;
3369 $lastoutmax ? $out->slice('0:'.($lastoutmax-1))->sever : empty(indx);
3370 }
3371 *PDL::which = \&which;
3372 EOD
3373 },
3374 {Name => 'which_both',
3375 Pars => 'mask(n); indx [o] inds(n); indx [o]notinds(n); indx [o]lastout(); indx [o]lastoutn()',
3376 Variables => 'PDL_Indx dm=0; int dm2=0;',
3377 Elseclause => "else { \n \$notinds(n => dm2)=n; \n dm2++;\n }",
3378 Outclause => '$lastout() = dm; $lastoutn() = dm2; loop(n=dm) %{ $inds() = -1; %} loop(n=dm2) %{ $notinds() = -1; %}',
3379 Doc => $doc_which_both,
3380 PMCode=>pp_line_numbers(__LINE__, <<'EOD'),
3381 sub which_both { my ($this,$outi,$outni) = @_;
3382 $this = $this->flat;
3383 $outi //= $this->nullcreate;
3384 $outni //= $this->nullcreate;
3385 PDL::_which_both_int($this,$outi,$outni,my $lastout = $this->nullcreate,my $lastoutn = $this->nullcreate);
3386 my $lastoutmax = $lastout->max->sclr;
3387 $outi = $lastoutmax ? $outi->slice('0:'.($lastoutmax-1))->sever : empty(indx);
3388 return $outi if !wantarray;
3389 my $lastoutnmax = $lastoutn->max->sclr;
3390 ($outi, $lastoutnmax ? $outni->slice('0:'.($lastoutnmax-1))->sever : empty(indx));
3391 }
3392 *PDL::which_both = \&which_both;
3393 EOD
3394 }
3395 )
3396 {
3397 pp_def($_->{Name},
3398 HandleBad => 1,
3399 Doc => $_->{Doc},
3400 Pars => $_->{Pars},
3401 GenericTypes => [ppdefs_all],
3402 PMCode => $_->{PMCode},
3403 Code => $_->{Variables} .'
3404 loop(n) %{
3405 if ( $mask() PDL_IF_BAD(&& $ISGOOD($mask()),) ) {
3406 $inds(n => dm) = n;
3407 dm++;
3408 }'.$_->{Elseclause}.'
3409 %}'.$_->{Outclause},
3410 );
3411 }
3412  
3413 pp_def('whichover',
3414 HandleBad => 1,
3415 Inplace => 1,
3416 Pars => 'a(n); [o]o(n)',
3417 GenericTypes => [ppdefs_all],
3418 Code => <<'EOF',
3419 PDL_Indx last = 0;
3420 loop(n) %{
3421 if ($a() PDL_IF_BAD(&& $ISGOOD($a()),)) $o(n=>last++) = n;
3422 %}
3423 loop(n=last) %{ $o() = -1; %}
3424 EOF
3425 Doc => <<'EOF',
3426 =for ref
3427  
3428 Collects the coordinates of non-zero, non-bad values in each 1D mask in
3429 ndarray at the start of the output, and fills the rest with -1.
3430  
3431 By using L<PDL::Slices/xchg> etc. it is possible to use I<any> dimension.
3432  
3433 =for example
3434  
3435 my $a = pdl q[3 4 2 3 2 3 1];
3436 my $b = $a->uniq;
3437 my $c = +($a->dummy(0) == $b)->transpose;
3438 print $c, $c->whichover;
3439 # [
3440 # [0 0 0 0 0 0 1]
3441 # [0 0 1 0 1 0 0]
3442 # [1 0 0 1 0 1 0]
3443 # [0 1 0 0 0 0 0]
3444 # ]
3445 # [
3446 # [ 6 -1 -1 -1 -1 -1 -1]
3447 # [ 2 4 -1 -1 -1 -1 -1]
3448 # [ 0 3 5 -1 -1 -1 -1]
3449 # [ 1 -1 -1 -1 -1 -1 -1]
3450 # ]
3451  
3452 EOF
3453 );
3454  
3455 pp_def('approx_artol',
3456 Pars => 'got(); expected(); sbyte [o] result()',
3457 OtherPars => 'double atol; double rtol',
3458 OtherParsDefaults => { atol => 1e-6, rtol => 0 },
3459 GenericTypes => [ppdefs_all],
3460 ArgOrder => 1,
3461 HandleBad => 1,
3462 Code => pp_line_numbers(__LINE__, <<'EOF'),
3463 double atol2 = $COMP(atol)*$COMP(atol), rtol2 = $COMP(rtol)*$COMP(rtol);
3464 PDL_IF_BAD(char got_badflag = !!$PDLSTATEISBAD(got); char exp_badflag = !!$PDLSTATEISBAD(expected);,)
3465 broadcastloop %{
3466 $GENERIC() expctd = $expected();
3467 if (PDL_ISNAN_$PPSYM()($got()) && PDL_ISNAN_$PPSYM()(expctd)) { $result() = 1; continue; }
3468 if (PDL_ISNAN_$PPSYM()($got()) || PDL_ISNAN_$PPSYM()(expctd)) { $result() = 0; continue; }
3469 PDL_IF_BAD(
3470 if ((got_badflag && $ISBAD(got())) && (exp_badflag && $ISBADVAR(expctd,expected))) { $result() = 1; continue; }
3471 if ((got_badflag && $ISBAD(got())) || (exp_badflag && $ISBADVAR(expctd,expected))) { $result() = 0; continue; }
3472 ,)
3473 if ($got() == expctd) { $result() = 1; continue; }
3474 $GENERIC() diff = $got() - expctd;
3475 PDL_LDouble abs_diff2 = PDL_IF_GENTYPE_REAL(
3476 diff * diff,
3477 (creall(diff) * creall(diff)) + (cimagl(diff) * cimagl(diff))
3478 );
3479 if (abs_diff2 <= atol2) { $result() = 1; continue; }
3480 PDL_LDouble rel_diff2 = rtol2 * PDL_IF_GENTYPE_REAL(
3481 expctd * expctd,
3482 ((creall(expctd) * creall(expctd)) + (cimagl(expctd) * cimagl(expctd)))
3483 );
3484 if (abs_diff2 <= rel_diff2) { $result() = 1; continue; }
3485 $result() = 0;
3486 %}
3487 EOF
3488 Doc => <<'EOF',
3489 =for ref
3490  
3491 Returns C<sbyte> mask whether C<< abs($got()-$expected())> <= >> either
3492 absolute or relative (C<rtol> * C<$expected()>) tolerances.
3493  
3494 Relative tolerance defaults to zero, and absolute tolerance defaults to
3495 C<1e-6>, for compatibility with L<PDL::Core/approx>.
3496  
3497 Works with complex numbers, and to avoid expensive C<sqrt>ing uses the
3498 squares of the input quantities and differences. Bear this in mind for
3499 numbers outside the range (for C<double>) of about C<1e-154..1e154>.
3500  
3501 Handles C<NaN>s by showing them approximately equal (i.e. true in the
3502 output) if both values are C<NaN>, and not otherwise.
3503  
3504 Adapted from code by Edward Baudrez, test changed from C<< < >> to C<< <= >>.
3505 EOF
3506 BadDoc => <<'EOF',
3507 Handles bad values similarly to C<NaN>s, above. This includes if only
3508 one of the two input ndarrays has their badflag true.
3509 EOF
3510 );
3511  
3512 pp_add_exported("", 'where');
3513 pp_addpm(<<'EOD');
3514 =head2 where
3515  
3516 =for ref
3517  
3518 Use a mask to select values from one or more data PDLs
3519  
3520 C<where> accepts one or more data ndarrays and a mask ndarray. It
3521 returns a list of output ndarrays, corresponding to the input data
3522 ndarrays. Each output ndarray is a 1-dimensional list of values in its
3523 corresponding data ndarray. The values are drawn from locations where
3524 the mask is nonzero.
3525  
3526 The output PDLs are still connected to the original data PDLs, for the
3527 purpose of dataflow.
3528  
3529 C<where> combines the functionality of L</which> and L<index|PDL::Slices/index>
3530 into a single operation.
3531  
3532 BUGS:
3533  
3534 While C<where> works OK for most N-dimensional cases, it does not
3535 broadcast properly over (for example) the (N+1)th dimension in data
3536 that is compared to an N-dimensional mask. Use C<whereND> for that.
3537  
3538 =for example
3539  
3540 $i = $x->where($x+5 > 0); # $i contains those elements of $x
3541 # where mask ($x+5 > 0) is 1
3542 $i .= -5; # Set those elements (of $x) to -5. Together, these
3543 # commands clamp $x to a maximum of -5.
3544  
3545 It is also possible to use the same mask for several ndarrays with
3546 the same call:
3547  
3548 ($i,$j,$k) = where($x,$y,$z, $x+5>0);
3549  
3550 Note: C<$i> is always 1-D, even if C<$x> is E<gt>1-D.
3551  
3552 WARNING: The first argument
3553 (the values) and the second argument (the mask) currently have to have
3554 the exact same dimensions (or horrible things happen). You *cannot*
3555 broadcast over a smaller mask, for example.
3556  
3557 =cut
3558  
3559 sub PDL::where :lvalue {
3560 barf "Usage: where( \$pdl1, ..., \$pdlN, \$mask )\n" if @_ == 1;
3561 my $mask = pop->flat->which;
3562 @_ == 1 ? $_[0]->flat->index($mask) : map $_->flat->index($mask), @_;
3563 }
3564 *where = \&PDL::where;
3565  
3566 EOD
3567  
3568 pp_add_exported("", 'where_both');
3569 pp_addpm(<<'EOD');
3570 =head2 where_both
3571  
3572 =for ref
3573  
3574 Returns slices (non-zero in mask, zero) of an ndarray according to a mask
3575  
3576 =for usage
3577  
3578 ($match_vals, $non_match_vals) = where_both($pdl, $mask);
3579  
3580 This works like L</which_both>, but (flattened) data-flowing slices
3581 rather than index-sets are returned.
3582  
3583 =for example
3584  
3585 pdl> p $x = sequence(10) + 2
3586 [2 3 4 5 6 7 8 9 10 11]
3587 pdl> ($big, $small) = where_both($x, $x > 5); p "$big\n$small"
3588 [6 7 8 9 10 11]
3589 [2 3 4 5]
3590 pdl> p $big += 2, $small -= 1
3591 [8 9 10 11 12 13] [1 2 3 4]
3592 pdl> p $x
3593 [1 2 3 4 8 9 10 11 12 13]
3594  
3595 =cut
3596  
3597 sub PDL::where_both {
3598 barf "Usage: where_both(\$pdl, \$mask)\n" if @_ != 2;
3599 my ($arr, $mask) = @_; # $mask has 0==false, 1==true
3600 my $arr_flat = $arr->flat;
3601 map $arr_flat->index1d($_), PDL::which_both($mask);
3602 }
3603 *where_both = \&PDL::where_both;
3604 EOD
3605  
3606 pp_add_exported("", 'whereND whereND_both');
3607 pp_addpm(<<'EOD');
3608 =head2 whereND
3609  
3610 =for ref
3611  
3612 C<where> with support for ND masks and broadcasting
3613  
3614 C<whereND> accepts one or more data ndarrays and a
3615 mask ndarray. It returns a list of output ndarrays,
3616 corresponding to the input data ndarrays. The values
3617 are drawn from locations where the mask is nonzero.
3618  
3619 C<whereND> differs from C<where> in that the mask
3620 dimensionality is preserved which allows for
3621 proper broadcasting of the selection operation over
3622 higher dimensions.
3623  
3624 As with C<where> the output PDLs are still connected
3625 to the original data PDLs, for the purpose of dataflow.
3626  
3627 =for usage
3628  
3629 $sdata = whereND $data, $mask
3630 ($s1, $s2, ..., $sn) = whereND $d1, $d2, ..., $dn, $mask
3631  
3632 where
3633  
3634 $data is M dimensional
3635 $mask is N < M dimensional
3636 dims($data) 1..N == dims($mask) 1..N
3637 with broadcasting over N+1 to M dimensions
3638  
3639 =for example
3640  
3641 $data = sequence(4,3,2); # example data array
3642 $mask4 = (random(4)>0.5); # example 1-D mask array, has $n4 true values
3643 $mask43 = (random(4,3)>0.5); # example 2-D mask array, has $n43 true values
3644 $sdat4 = whereND $data, $mask4; # $sdat4 is a [$n4,3,2] pdl
3645 $sdat43 = whereND $data, $mask43; # $sdat43 is a [$n43,2] pdl
3646  
3647 Just as with C<where>, you can use the returned value in an
3648 assignment. That means that both of these examples are valid:
3649  
3650 # Used to create a new slice stored in $sdat4:
3651 $sdat4 = $data->whereND($mask4);
3652 $sdat4 .= 0;
3653 # Used in lvalue context:
3654 $data->whereND($mask4) .= 0;
3655  
3656 SEE ALSO:
3657  
3658 L</whichND> returns N-D indices into a multidimensional PDL, from a mask.
3659  
3660 =cut
3661  
3662 sub PDL::whereND :lvalue {
3663 barf "Usage: whereND( \$pdl1, ..., \$pdlN, \$mask )\n" if @_ == 1;
3664 my $mask = pop @_; # $mask has 0==false, 1==true
3665 my @to_return;
3666 my $n = PDL::sum($mask);
3667 my $maskndims = $mask->ndims;
3668 foreach my $arr (@_) {
3669 # count the number of dims in $mask and $arr
3670 # $mask = a b c d e f.....
3671 my @idims = dims($arr);
3672 splice @idims, 0, $maskndims; # pop off the number of dims in $mask
3673 if (!$n or $arr->isempty) {
3674 push @to_return, PDL->zeroes($arr->type, $n, @idims);
3675 next;
3676 }
3677 my $sub_i = $mask * ones($arr);
3678 my $where_sub_i = PDL::where($arr, $sub_i);
3679 my $ndim = 0;
3680 foreach my $id ($n, @idims[0..($#idims-1)]) {
3681 $where_sub_i = $where_sub_i->splitdim($ndim++,$id) if $n>0;
3682 }
3683 push @to_return, $where_sub_i;
3684 }
3685 return (@to_return == 1) ? $to_return[0] : @to_return;
3686 }
3687 *whereND = \&PDL::whereND;
3688  
3689 =head2 whereND_both
3690  
3691 =for ref
3692  
3693 C<where_both> with support for ND masks and broadcasting
3694  
3695 This works like L</whichND_both>, but data-flowing slices
3696 rather than index-sets are returned.
3697  
3698 C<whereND_both> differs from C<where_both> in that the mask
3699 dimensionality is preserved which allows for
3700 proper broadcasting of the selection operation over
3701 higher dimensions.
3702  
3703 As with C<where_both> the output PDLs are still connected
3704 to the original data PDLs, for the purpose of dataflow.
3705  
3706 =for usage
3707  
3708 ($match_vals, $non_match_vals) = whereND_both($pdl, $mask);
3709  
3710 =cut
3711  
3712 sub PDL::whereND_both :lvalue {
3713 barf "Usage: whereND_both(\$pdl, \$mask)\n" if @_ != 2;
3714 my ($arr, $mask) = @_; # $mask has 0==false, 1==true
3715 map $arr->indexND($_), PDL::whichND_both($mask);
3716 }
3717 *whereND_both = \&PDL::whereND_both;
3718 EOD
3719  
3720 pp_add_exported("", 'whichND whichND_both');
3721 pp_addpm(<<'EOD');
3722 =head2 whichND
3723  
3724 =for ref
3725  
3726 Return the coordinates of non-zero values in a mask.
3727  
3728 =for usage
3729  
3730 WhichND returns the N-dimensional coordinates of each nonzero value in
3731 a mask PDL with any number of dimensions. The returned values arrive
3732 as an array-of-vectors suitable for use in
3733 L<indexND|PDL::Slices/indexND> or L<range|PDL::Slices/range>.
3734  
3735 $coords = whichND($mask);
3736  
3737 returns a PDL containing the coordinates of the elements that are non-zero
3738 in C<$mask>, suitable for use in L<PDL::Slices/indexND>. The 0th dimension contains the
3739 full coordinate listing of each point; the 1st dimension lists all the points.
3740 For example, if $mask has rank 4 and 100 matching elements, then $coords has
3741 dimension 4x100.
3742  
3743 If no such elements exist, then whichND returns a structured empty PDL:
3744 an Nx0 PDL that contains no values (but matches, broadcasting-wise, with
3745 the vectors that would be produced if such elements existed).
3746  
3747 DEPRECATED BEHAVIOR IN LIST CONTEXT:
3748  
3749 whichND once delivered different values in list context than in scalar
3750 context, for historical reasons. In list context, it returned the
3751 coordinates transposed, as a collection of 1-PDLs (one per dimension)
3752 in a list. This usage is deprecated in PDL 2.4.10, and will cause a
3753 warning to be issued every time it is encountered. To avoid the
3754 warning, you can set the global variable "$PDL::whichND" to 's' to
3755 get scalar behavior in all contexts, or to 'l' to get list behavior in
3756 list context.
3757  
3758 In later versions of PDL, the deprecated behavior will disappear. Deprecated
3759 list context whichND expressions can be replaced with:
3760  
3761 @list = $x->whichND->mv(0,-1)->dog;
3762  
3763 SEE ALSO:
3764  
3765 L</which> finds coordinates of nonzero values in a 1-D mask.
3766  
3767 L</where> extracts values from a data PDL that are associated
3768 with nonzero values in a mask PDL.
3769  
3770 L<PDL::Slices/indexND> can be fed the coordinates to return the values.
3771  
3772 =for example
3773  
3774 pdl> $s=sequence(10,10,3,4)
3775 pdl> ($x, $y, $z, $w)=whichND($s == 203); p $x, $y, $z, $w
3776 [3] [0] [2] [0]
3777 pdl> print $s->at(list(cat($x,$y,$z,$w)))
3778 203
3779  
3780 =cut
3781  
3782 sub _one2nd {
3783 my ($mask, $ind) = @_;
3784 my $ndims = my @mdims = $mask->dims;
3785 # In the empty case, explicitly return the correct type of structured empty
3786 return PDL->new_from_specification(indx, $ndims, 0) if !$ind->nelem;
3787 my $mult = ones(indx, $ndims);
3788 $mult->index($_+1) .= $mult->index($_) * $mdims[$_] for 0..$#mdims-1;
3789 for my $i (0..$#mdims) {
3790 my $s = $ind->index($i);
3791 $s /= $mult->index($i);
3792 $s %= $mdims[$i];
3793 }
3794 $ind;
3795 }
3796  
3797 *whichND = \&PDL::whichND;
3798 sub PDL::whichND {
3799 my $mask = PDL->topdl(shift);
3800  
3801 # List context: generate a perl list by dimension
3802 if(wantarray) {
3803 if(!defined($PDL::whichND)) {
3804 printf STDERR "whichND: WARNING - list context deprecated. Set \$PDL::whichND. Details in pod.";
3805 } elsif($PDL::whichND =~ m/l/i) {
3806 # old list context enabled by setting $PDL::whichND to 'l'
3807 return $mask->one2nd($mask->flat->which);
3808 }
3809 # if $PDL::whichND does not contain 'l' or 'L', fall through to scalar context
3810 }
3811  
3812 # Scalar context: generate an N-D index ndarray
3813 my $ndims = $mask->getndims;
3814 return PDL->new_from_specification(indx,$ndims,0) if !$mask->nelem;
3815 return $mask ? pdl(indx,0) : PDL->new_from_specification(indx,0) if !$ndims;
3816 _one2nd($mask, $mask->flat->which->dummy(0,$ndims)->sever);
3817 }
3818  
3819 =head2 whichND_both
3820  
3821 =for ref
3822  
3823 Return the coordinates of non-zero values in a mask.
3824  
3825 =for usage
3826  
3827 Like L</which_both>, but returns the N-dimensional coordinates (like
3828 L</whichND>) of the nonzero, zero values in the mask PDL. The
3829 returned values arrive as an array-of-vectors suitable for use in
3830 L<indexND|PDL::Slices/indexND> or L<range|PDL::Slices/range>.
3831 Added in 2.099.
3832  
3833 ($nonzero_coords, $zero_coords) = whichND_both($mask);
3834  
3835 SEE ALSO:
3836  
3837 L</which> finds coordinates of nonzero values in a 1-D mask.
3838  
3839 L</where> extracts values from a data PDL that are associated
3840 with nonzero values in a mask PDL.
3841  
3842 L<PDL::Slices/indexND> can be fed the coordinates to return the values.
3843  
3844 =for example
3845  
3846 pdl> $s=sequence(10,10,3,4)
3847 pdl> ($x, $y, $z, $w)=whichND($s == 203); p $x, $y, $z, $w
3848 [3] [0] [2] [0]
3849 pdl> print $s->at(list(cat($x,$y,$z,$w)))
3850 203
3851  
3852 =cut
3853  
3854 *whichND_both = \&PDL::whichND_both;
3855 sub PDL::whichND_both {
3856 my $mask = PDL->topdl(shift);
3857 return ((PDL->new_from_specification(indx,$mask->ndims,0))x2) if !$mask->nelem;
3858 my $ndims = $mask->getndims;
3859 if (!$ndims) {
3860 my ($t, $f) = (pdl(indx,0), PDL->new_from_specification(indx,0));
3861 return $mask ? ($t,$f) : ($f,$t);
3862 }
3863 map _one2nd($mask, $_->dummy(0,$ndims)->sever), $mask->flat->which_both;
3864 }
3865 EOD
3866  
3867 #
3868 # Set operations suited for manipulation of the operations above.
3869 #
3870  
3871 pp_add_exported("", 'setops');
3872 pp_addpm(<<'EOD');
3873 =head2 setops
3874  
3875 =for ref
3876  
3877 Implements simple set operations like union and intersection
3878  
3879 =for usage
3880  
3881 Usage: $set = setops($x, <OPERATOR>, $y);
3882  
3883 The operator can be C<OR>, C<XOR> or C<AND>. This is then applied
3884 to C<$x> viewed as a set and C<$y> viewed as a set. Set theory says
3885 that a set may not have two or more identical elements, but setops
3886 takes care of this for you, so C<$x=pdl(1,1,2)> is OK. The functioning
3887 is as follows:
3888  
3889 =over
3890  
3891 =item C<OR>
3892  
3893 The resulting vector will contain the elements that are either in C<$x>
3894 I<or> in C<$y> or both. This is the union in set operation terms
3895  
3896 =item C<XOR>
3897  
3898 The resulting vector will contain the elements that are either in C<$x>
3899 or C<$y>, but not in both. This is
3900  
3901 Union($x, $y) - Intersection($x, $y)
3902  
3903 in set operation terms.
3904  
3905 =item C<AND>
3906  
3907 The resulting vector will contain the intersection of C<$x> and C<$y>, so
3908 the elements that are in both C<$x> and C<$y>. Note that for convenience
3909 this operation is also aliased to L</intersect>.
3910  
3911 =back
3912  
3913 It should be emphasized that these routines are used when one or both of
3914 the sets C<$x>, C<$y> are hard to calculate or that you get from a separate
3915 subroutine.
3916  
3917 Finally IDL users might be familiar with Craig Markwardt's C<cmset_op.pro>
3918 routine which has inspired this routine although it was written independently
3919 However the present routine has a few less options (but see the examples)
3920  
3921 =for example
3922  
3923 You will very often use these functions on an index vector, so that is
3924 what we will show here. We will in fact something slightly silly. First
3925 we will find all squares that are also cubes below 10000.
3926  
3927 Create a sequence vector:
3928  
3929 pdl> $x = sequence(10000)
3930  
3931 Find all odd and even elements:
3932  
3933 pdl> ($even, $odd) = which_both( ($x % 2) == 0)
3934  
3935 Find all squares
3936  
3937 pdl> $squares= which(ceil(sqrt($x)) == floor(sqrt($x)))
3938  
3939 Find all cubes (being careful with roundoff error!)
3940  
3941 pdl> $cubes= which(ceil($x**(1.0/3.0)) == floor($x**(1.0/3.0)+1e-6))
3942  
3943 Then find all squares that are cubes:
3944  
3945 pdl> $both = setops($squares, 'AND', $cubes)
3946  
3947 And print these (assumes that C<PDL::NiceSlice> is loaded!)
3948  
3949 pdl> p $x($both)
3950 [0 1 64 729 4096]
3951  
3952 Then find all numbers that are either cubes or squares, but not both:
3953  
3954 pdl> $cube_xor_square = setops($squares, 'XOR', $cubes)
3955  
3956 pdl> p $cube_xor_square->nelem()
3957 112
3958  
3959 So there are a total of 112 of these!
3960  
3961 Finally find all odd squares:
3962  
3963 pdl> $odd_squares = setops($squares, 'AND', $odd)
3964  
3965  
3966 Another common occurrence is to want to get all objects that are
3967 in C<$x> and in the complement of C<$y>. But it is almost always best
3968 to create the complement explicitly since the universe that both are
3969 taken from is not known. Thus use L</which_both> if possible
3970 to keep track of complements.
3971  
3972 If this is impossible the best approach is to make a temporary:
3973  
3974 This creates an index vector the size of the universe of the sets and
3975 set all elements in C<$y> to 0
3976  
3977 pdl> $tmp = ones($n_universe); $tmp($y) .= 0;
3978  
3979 This then finds the complement of C<$y>
3980  
3981 pdl> $C_b = which($tmp == 1);
3982  
3983 and this does the final selection:
3984  
3985 pdl> $set = setops($x, 'AND', $C_b)
3986  
3987 =cut
3988  
3989 *setops = \&PDL::setops;
3990  
3991 sub PDL::setops {
3992  
3993 my ($x, $op, $y)=@_;
3994  
3995 # Check that $x and $y are 1D.
3996 if ($x->ndims() > 1 || $y->ndims() > 1) {
3997 warn 'setops: $x and $y must be 1D - flattening them!'."\n";
3998 $x = $x->flat;
3999 $y = $y->flat;
4000 }
4001  
4002 #Make sure there are no duplicate elements.
4003 $x=$x->uniq;
4004 $y=$y->uniq;
4005  
4006 my $result;
4007  
4008 if ($op eq 'OR') {
4009 # Easy...
4010 $result = uniq(append($x, $y));
4011 } elsif ($op eq 'XOR') {
4012 # Make ordered list of set union.
4013 my $union = append($x, $y)->qsort;
4014 # Index lists.
4015 my $s1=zeroes(byte, $union->nelem());
4016 my $s2=zeroes(byte, $union->nelem());
4017  
4018 # Find indices which are duplicated - these are to be excluded
4019 #
4020 # We do this by comparing x with x shifted each way.
4021 my $i1 = which($union != rotate($union, 1));
4022 my $i2 = which($union != rotate($union, -1));
4023 #
4024 # We then mark/mask these in the s1 and s2 arrays to indicate which ones
4025 # are not equal to their neighbours.
4026 #
4027 my $ts;
4028 ($ts = $s1->index($i1)) .= byte(1) if $i1->nelem() > 0;
4029 ($ts = $s2->index($i2)) .= byte(1) if $i2->nelem() > 0;
4030  
4031 my $inds=which($s1 == $s2);
4032  
4033 if ($inds->nelem() > 0) {
4034 return $union->index($inds);
4035 } else {
4036 return $inds;
4037 }
4038  
4039 } elsif ($op eq 'AND') {
4040 # The intersection of the arrays.
4041 return $x if $x->isempty;
4042 return $y if $y->isempty;
4043 # Make ordered list of set union.
4044 my $union = append($x, $y)->qsort;
4045 return $union->where($union == rotate($union, -1))->uniq;
4046 } else {
4047 print "The operation $op is not known!";
4048 return -1;
4049 }
4050  
4051 }
4052 EOD
4053  
4054 pp_add_exported("", 'intersect');
4055 pp_addpm(<<'EOD');
4056 =head2 intersect
4057  
4058 =for ref
4059  
4060 Calculate the intersection of two ndarrays
4061  
4062 =for usage
4063  
4064 Usage: $set = intersect($x, $y);
4065  
4066 This routine is merely a simple interface to L</setops>. See
4067 that for more information
4068  
4069 =for example
4070  
4071 Find all numbers less that 100 that are of the form 2*y and 3*x
4072  
4073 pdl> $x=sequence(100)
4074 pdl> $factor2 = which( ($x % 2) == 0)
4075 pdl> $factor3 = which( ($x % 3) == 0)
4076 pdl> $ii=intersect($factor2, $factor3)
4077 pdl> p $x($ii)
4078 [0 6 12 18 24 30 36 42 48 54 60 66 72 78 84 90 96]
4079  
4080 =cut
4081  
4082 *intersect = \&PDL::intersect;
4083  
4084 sub PDL::intersect { setops($_[0], 'AND', $_[1]) }
4085 EOD
4086  
4087 pp_add_macros(
4088 PCHDF => sub {my ($k, $x, $s, $out) = @_; '
4089 /* PDL version: K, X, S are var names, 4th param output */
4090 /* ***PURPOSE Computes divided differences for DPCHCE and DPCHSP */
4091 /* DPCHDF: DPCHIP Finite Difference Formula */
4092 /* Uses a divided difference formulation to compute a K-point approx- */
4093 /* imation to the derivative at X(K) based on the data in X and S. */
4094 /* Called by DPCHCE and DPCHSP to compute 3- and 4-point boundary */
4095 /* derivative approximations. */
4096 /* ---------------------------------------------------------------------- */
4097 /* On input: */
4098 /* K is the order of the desired derivative approximation. */
4099 /* K must be at least 3 (error return if not). */
4100 /* X contains the K values of the independent variable. */
4101 /* X need not be ordered, but the values **MUST** be */
4102 /* distinct. (Not checked here.) */
4103 /* S contains the associated slope values: */
4104 /* S(I) = (F(I+1)-F(I))/(X(I+1)-X(I)), I=1(1)K-1. */
4105 /* (Note that S need only be of length K-1.) */
4106 /* On return: */
4107 /* S will be destroyed. */
4108 /* IERR will be set to -1 if K.LT.2 . */
4109 /* DPCHDF will be set to the desired derivative approximation if */
4110 /* IERR=0 or to zero if IERR=-1. */
4111 /* ---------------------------------------------------------------------- */
4112 /* ***SEE ALSO DPCHCE, DPCHSP */
4113 /* ***REFERENCES Carl de Boor, A Practical Guide to Splines, Springer- */
4114 /* Verlag, New York, 1978, pp. 10-16. */
4115 /* CHECK FOR LEGAL VALUE OF K. */
4116 {
4117 /* Local variables */
4118 PDL_Indx i, j, k_cached = '.$k.';
4119 $GENERIC() *x = '.$x.', *s = '.$s.';
4120 if (k_cached < 3) $CROAK("K LESS THAN THREE");
4121 /* COMPUTE COEFFICIENTS OF INTERPOLATING POLYNOMIAL. */
4122 for (j = 2; j < k_cached; ++j) {
4123 PDL_Indx itmp = k_cached - j;
4124 for (i = 0; i < itmp; ++i)
4125 s[i] = (s[i+1] - s[i]) / (x[i + j] - x[i]);
4126 }
4127 /* EVALUATE DERIVATIVE AT X(K). */
4128 $GENERIC() value = s[0];
4129 for (i = 1; i < k_cached-1; ++i)
4130 value = s[i] + value * (x[k_cached-1] - x[i]);
4131 '.$out.' = value;
4132 }
4133 '},
4134 SIGN => sub {my ($a, $b) = @_; "(($b) >= 0 ? PDL_ABS($a) : -PDL_ABS($a))"},
4135 PCHST => sub {my ($a, $b) = @_;
4136 "((($a) == 0. || ($b) == 0.) ? 0. : \$SIGN(1, ($a)) * \$SIGN(1, ($b)))"
4137 },
4138 CHFIE => sub {my ($x1, $x2, $f1, $f2, $d1, $d2, $a, $b, $out) = @_; '
4139 /* ***PURPOSE Evaluates integral of a single cubic for DPCHIA */
4140 /* DCHFIE: Cubic Hermite Function Integral Evaluator. */
4141 /* Called by DPCHIA to evaluate the integral of a single cubic (in */
4142 /* Hermite form) over an arbitrary interval (A,B). */
4143 /* ---------------------------------------------------------------------- */
4144 /* Parameters: */
4145 /* VALUE -- (output) value of the requested integral. */
4146 /* X1,X2 -- (input) endpoints if interval of definition of cubic. */
4147 /* F1,F2 -- (input) function values at the ends of the interval. */
4148 /* D1,D2 -- (input) derivative values at the ends of the interval. */
4149 /* A,B -- (input) endpoints of interval of integration. */
4150 /* ***SEE ALSO DPCHIA */
4151 /* Programming notes: */
4152 /* 1. There is no error return from this routine because zero is */
4153 /* indeed the mathematically correct answer when X1.EQ.X2 . */
4154 do {
4155 if ('.$x1.' == '.$x2.') {
4156 '.$out.' = 0.; break;
4157 }
4158 $GENERIC() h = '.$x2.' - '.$x1.';
4159 $GENERIC() ta1 = ('.$a.' - '.$x1.') / h;
4160 $GENERIC() ta2 = ('.$x2.' - '.$a.') / h;
4161 $GENERIC() tb1 = ('.$b.' - '.$x1.') / h;
4162 $GENERIC() tb2 = ('.$x2.' - '.$b.') / h;
4163 /* Computing 3rd power */
4164 $GENERIC() ua1 = ta1 * (ta1 * ta1);
4165 $GENERIC() phia1 = ua1 * (2. - ta1);
4166 $GENERIC() psia1 = ua1 * (3. * ta1 - 4.);
4167 /* Computing 3rd power */
4168 $GENERIC() ua2 = ta2 * (ta2 * ta2);
4169 $GENERIC() phia2 = ua2 * (2. - ta2);
4170 $GENERIC() psia2 = -ua2 * (3. * ta2 - 4.);
4171 /* Computing 3rd power */
4172 $GENERIC() ub1 = tb1 * (tb1 * tb1);
4173 $GENERIC() phib1 = ub1 * (2. - tb1);
4174 $GENERIC() psib1 = ub1 * (3. * tb1 - 4.);
4175 /* Computing 3rd power */
4176 $GENERIC() ub2 = tb2 * (tb2 * tb2);
4177 $GENERIC() phib2 = ub2 * (2. - tb2);
4178 $GENERIC() psib2 = -ub2 * (3. * tb2 - 4.);
4179 $GENERIC() fterm = '.$f1.' * (phia2 - phib2) + '.$f2.' * (phib1 - phia1);
4180 $GENERIC() dterm = ('.$d1.' * (psia2 - psib2) + '.$d2.' * (psib1 - psia1)) * (h / 6.);
4181 '.$out.' = 0.5 * h * (fterm + dterm);
4182 } while(0)
4183 '},
4184 PCHID => sub {my ($ia, $ib, $out) = @_; '
4185 /* Programming notes: */
4186 /* 1. This routine uses a special formula that is valid only for */
4187 /* integrals whose limits coincide with data values. This is */
4188 /* mathematically equivalent to, but much more efficient than, */
4189 /* calls to DCHFIE. */
4190 /* VALIDITY-CHECK ARGUMENTS. */
4191 do {
4192 /* FUNCTION DEFINITION IS OK, GO ON. */
4193 $skip() = 1;
4194 if ('.$ia.' < 0 || '.$ia.' > $SIZE(n)-1 || '.$ib.' < 0 || '.$ib.' > $SIZE(n)-1) {
4195 $ierr() = -4;
4196 $CROAK("IA OR IB OUT OF RANGE");
4197 }
4198 $ierr() = 0;
4199 /* COMPUTE INTEGRAL VALUE. */
4200 if ('.$ia.' == '.$ib.') { '.$out.' = 0; continue; }
4201 PDL_Indx low = PDLMIN('.$ia.','.$ib.'), iup = PDLMAX('.$ia.','.$ib.');
4202 $GENERIC() sum = 0.;
4203 loop (n=low:iup) %{
4204 $GENERIC() h = $x(n=>n+1) - $x();
4205 sum += h * ($f() + $f(n=>n+1) + ($d() - $d(n=>n+1)) * (h / 6.));
4206 %}
4207 '.$out.' = 0.5 * ('.$ia.' > '.$ib.' ? -sum : sum);
4208 } while(0)
4209 '},
4210 CHFD => sub {my ($do_deriv) = @_; '
4211 /* Programming notes: */
4212 /* 2. Most of the coding between the call to DCHFDV and the end of */
4213 /* the IR-loop could be eliminated if it were permissible to */
4214 /* assume that XE is ordered relative to X. */
4215 /* 3. DCHFDV does not assume that X1 is less than X2. thus, it would */
4216 /* be possible to write a version of DPCHFD that assumes a strict- */
4217 /* ly decreasing X-array by simply running the IR-loop backwards */
4218 /* (and reversing the order of appropriate tests). */
4219 /* 4. The present code has a minor bug, which I have decided is not */
4220 /* worth the effort that would be required to fix it. */
4221 /* If XE contains points in [X(N-1),X(N)], followed by points .LT. */
4222 /* X(N-1), followed by points .GT.X(N), the extrapolation points */
4223 /* will be counted (at least) twice in the total returned in IERR. */
4224 /* VALIDITY-CHECK ARGUMENTS. */
4225 if (!$skip()) {
4226 loop (n=1) %{
4227 if ($x() > $x(n=>n-1)) continue;
4228 $ierr() = -3;
4229 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
4230 %}
4231 }
4232 /* FUNCTION DEFINITION IS OK, GO ON. */
4233 $ierr() = 0;
4234 $skip() = 1;
4235 /* LOOP OVER INTERVALS. ( INTERVAL INDEX IS IL = IR-1 . ) */
4236 /* ( INTERVAL IS X(IL).LE.X.LT.X(IR) . ) */
4237 PDL_Indx n = $SIZE(n), ne = $SIZE(ne);
4238 PDL_Indx jfirst = 0, ir;
4239 for (ir = 1; ir < n && jfirst < ne; ++ir) {
4240 /* SKIP OUT OF LOOP IF HAVE PROCESSED ALL EVALUATION POINTS. */
4241 /* LOCATE ALL POINTS IN INTERVAL. */
4242 char located = 0;
4243 PDL_Indx j = jfirst;
4244 loop (ne=jfirst) %{
4245 j = ne;
4246 if ($xe() >= $x(n=>ir)) {
4247 located = 1;
4248 break;
4249 }
4250 %}
4251 if (!located || ir == n-1)
4252 j = ne;
4253 /* HAVE LOCATED FIRST POINT BEYOND INTERVAL. */
4254 PDL_Indx nj = j - jfirst;
4255 /* SKIP EVALUATION IF NO POINTS IN INTERVAL. */
4256 if (nj == 0)
4257 continue;
4258 /* EVALUATE CUBIC AT XE(I), I = JFIRST (1) J-1 . */
4259 /* ---------------------------------------------------------------- */
4260 PDL_Indx next[] = {0,0};
4261 do { /* inline dchfdv */
4262 /* Local variables */
4263 $GENERIC() x1 = $x(n=>ir-1), x2 = $x(n=>ir);
4264 $GENERIC() f1 = $f(n=>ir-1), f2 = $f(n=>ir);
4265 $GENERIC() d1 = $d(n=>ir-1), d2 = $d(n=>ir);
4266 $GENERIC() h = x2 - x1;
4267 if (h == 0.)
4268 $CROAK("INTERVAL ENDPOINTS EQUAL");
4269 /* INITIALIZE. */
4270 $GENERIC() xmi = PDLMIN(0.,h);
4271 $GENERIC() xma = PDLMAX(0.,h);
4272 /* COMPUTE CUBIC COEFFICIENTS (EXPANDED ABOUT X1). */
4273 $GENERIC() delta = (f2 - f1) / h;
4274 $GENERIC() del1 = (d1 - delta) / h;
4275 $GENERIC() del2 = (d2 - delta) / h;
4276 /* (DELTA IS NO LONGER NEEDED.) */
4277 $GENERIC() c2 = -(del1 + del1 + del2);
4278 '.($do_deriv ? '$GENERIC() c2t2 = c2 + c2;' : '').'
4279 $GENERIC() c3 = (del1 + del2) / h;
4280 /* (H, DEL1 AND DEL2 ARE NO LONGER NEEDED.) */
4281 '.($do_deriv ? '$GENERIC() c3t3 = c3 + c3 + c3;' : '').'
4282 /* EVALUATION LOOP. */
4283 loop (ne=:nj) %{
4284 $GENERIC() x = $xe(ne=>ne+jfirst) - x1;
4285 $fe(ne=>ne+jfirst) = f1 + x * (d1 + x * (c2 + x * c3));
4286 '.($do_deriv ? '$de(ne=>ne+jfirst) = d1 + x * (c2t2 + x * c3t3);' : '').'
4287 /* COUNT EXTRAPOLATION POINTS. */
4288 if (x < xmi)
4289 ++next[0];
4290 if (x > xma)
4291 ++next[1];
4292 /* (NOTE REDUNDANCY--IF EITHER CONDITION IS TRUE, OTHER IS FALSE.) */
4293 %}
4294 } while (0); /* end inline dchfdv */
4295 /* ---------------------------------------------------------------- */
4296 if (next[1] != 0) {
4297 /* IN THE CURRENT SET OF XE-POINTS, THERE ARE NEXT(2) TO THE */
4298 /* RIGHT OF X(IR). */
4299 /* THESE ARE ACTUALLY EXTRAPOLATION POINTS. */
4300 $ierr() += next[1];
4301 }
4302 if (next[0] != 0) {
4303 /* IN THE CURRENT SET OF XE-POINTS, THERE ARE NEXT(1) TO THE */
4304 /* LEFT OF X(IR-1). */
4305 if (ir < 2) {
4306 /* THESE ARE ACTUALLY EXTRAPOLATION POINTS. */
4307 $ierr() += next[0];
4308 jfirst = j;
4309 continue;
4310 }
4311 /* XE IS NOT ORDERED RELATIVE TO X, SO MUST ADJUST */
4312 /* EVALUATION INTERVAL. */
4313 /* FIRST, LOCATE FIRST POINT TO LEFT OF X(IR-1). */
4314 located = 0;
4315 PDL_Indx i = jfirst;
4316 loop (ne=jfirst:j) %{
4317 i = ne;
4318 if ($xe() < $x(n=>ir-1)) {
4319 located = 1;
4320 break;
4321 }
4322 %}
4323 if (!located) {
4324 /* NOTE-- CANNOT DROP THROUGH HERE UNLESS THERE IS AN ERROR */
4325 /* IN DCHFDV. */
4326 $ierr() = -5;
4327 $CROAK("ERROR RETURN FROM DCHFDV -- FATAL");
4328 }
4329 /* RESET J. (THIS WILL BE THE NEW JFIRST.) */
4330 j = i;
4331 /* NOW FIND OUT HOW FAR TO BACK UP IN THE X-ARRAY. */
4332 loop (n=:ir) %{
4333 i = n;
4334 if ($xe(ne=>j) < $x())
4335 break;
4336 %}
4337 /* NB-- CAN NEVER DROP THROUGH HERE, SINCE XE(J).LT.X(IR-1). */
4338 /* AT THIS POINT, EITHER XE(J) .LT. X(1) */
4339 /* OR X(I-1) .LE. XE(J) .LT. X(I) . */
4340 /* RESET IR, RECOGNIZING THAT IT WILL BE INCREMENTED BEFORE */
4341 /* CYCLING. */
4342 /* Computing MAX */
4343 ir = PDLMAX(0,i-1);
4344 }
4345 jfirst = j;
4346 /* END OF IR-LOOP. */
4347 }
4348 '},
4349 );
4350  
4351 pp_def('pchip_chim',
4352 Pars => 'x(n); f(n); [o]d(n); indx [o]ierr();',
4353 RedoDimsCode => <<'EOF',
4354 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
4355 EOF
4356 Code => pp_line_numbers(__LINE__, <<'EOF'),
4357 /* Local variables */
4358 $GENERIC() dmax, hsumt3;
4359 PDL_Indx n = $SIZE(n);
4360 /* VALIDITY-CHECK ARGUMENTS. */
4361 loop (n=1) %{
4362 if ($x() > $x(n=>n-1)) continue;
4363 $ierr() = -1;
4364 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
4365 %}
4366 /* FUNCTION DEFINITION IS OK, GO ON. */
4367 $ierr() = 0;
4368 $GENERIC() h1 = $x(n=>1) - $x(n=>0);
4369 $GENERIC() del1 = ($f(n=>1) - $f(n=>0)) / h1;
4370 $GENERIC() dsave = del1;
4371 /* SPECIAL CASE N=2 -- USE LINEAR INTERPOLATION. */
4372 if (n <= 2) {
4373 $d(n=>0) = $d(n=>1) = del1;
4374 continue;
4375 }
4376 /* NORMAL CASE (N .GE. 3). */
4377 $GENERIC() h2 = $x(n=>2) - $x(n=>1);
4378 $GENERIC() del2 = ($f(n=>2) - $f(n=>1)) / h2;
4379 /* SET D(1) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */
4380 /* SHAPE-PRESERVING. */
4381 $GENERIC() hsum = h1 + h2;
4382 $GENERIC() w1 = (h1 + hsum) / hsum;
4383 $GENERIC() w2 = -h1 / hsum;
4384 $d(n=>0) = w1 * del1 + w2 * del2;
4385 if ($PCHST($d(n=>0), del1) <= 0.) {
4386 $d(n=>0) = 0.;
4387 } else if ($PCHST(del1, del2) < 0.) {
4388 /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */
4389 dmax = 3. * del1;
4390 if (PDL_ABS($d(n=>0)) > PDL_ABS(dmax)) {
4391 $d(n=>0) = dmax;
4392 }
4393 }
4394 /* LOOP THROUGH INTERIOR POINTS. */
4395 loop (n=1:-1) %{
4396 if (n != 1) {
4397 h1 = h2;
4398 h2 = $x(n=>n+1) - $x();
4399 hsum = h1 + h2;
4400 del1 = del2;
4401 del2 = ($f(n=>n+1) - $f()) / h2;
4402 }
4403 /* SET D(I)=0 UNLESS DATA ARE STRICTLY MONOTONIC. */
4404 $d() = 0.;
4405 $GENERIC() dtmp = $PCHST(del1, del2);
4406 if (dtmp <= 0) {
4407 if (dtmp == 0.) {
4408 /* COUNT NUMBER OF CHANGES IN DIRECTION OF MONOTONICITY. */
4409 if (del2 == 0.) {
4410 continue;
4411 }
4412 if ($PCHST(dsave, del2) < 0.) {
4413 ++($ierr());
4414 }
4415 dsave = del2;
4416 continue;
4417 }
4418 ++($ierr());
4419 dsave = del2;
4420 continue;
4421 }
4422 /* USE BRODLIE MODIFICATION OF BUTLAND FORMULA. */
4423 hsumt3 = hsum + hsum + hsum;
4424 w1 = (hsum + h1) / hsumt3;
4425 w2 = (hsum + h2) / hsumt3;
4426 /* Computing MAX */
4427 dmax = PDLMAX(PDL_ABS(del1),PDL_ABS(del2));
4428 /* Computing MIN */
4429 $GENERIC() dmin = PDLMIN(PDL_ABS(del1),PDL_ABS(del2));
4430 $GENERIC() drat1 = del1 / dmax;
4431 $GENERIC() drat2 = del2 / dmax;
4432 $d() = dmin / (w1 * drat1 + w2 * drat2);
4433 %}
4434 /* SET D(N) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */
4435 /* SHAPE-PRESERVING. */
4436 w1 = -h2 / hsum;
4437 w2 = (h2 + hsum) / hsum;
4438 $d(n=>n-1) = w1 * del1 + w2 * del2;
4439 if ($PCHST($d(n=>n-1), del2) <= 0.) {
4440 $d(n=>n-1) = 0.;
4441 } else if ($PCHST(del1, del2) < 0.) {
4442 /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */
4443 dmax = 3. * del2;
4444 if (PDL_ABS($d(n=>n-1)) > PDL_ABS(dmax)) {
4445 $d(n=>n-1) = dmax;
4446 }
4447 }
4448 EOF
4449 ParamDesc => {
4450 x => 'ordinate data',
4451 f => <<'EOF',
4452 array of dependent variable values to be
4453 interpolated. F(I) is value corresponding to
4454 X(I). C<pchip_chim> is designed for monotonic data, but it will
4455 work for any F-array. It will force extrema at points where
4456 monotonicity switches direction. If some other treatment of
4457 switch points is desired, DPCHIC should be used instead.
4458 EOF
4459 d => <<'EOF',
4460 array of derivative values at the data
4461 points. If the data are monotonic, these values will
4462 determine a monotone cubic Hermite function.
4463 EOF
4464 ierr => <<'EOF',
4465 Error status:
4466  
4467 =over
4468  
4469 =item *
4470  
4471 0 if successful.
4472  
4473 =item *
4474  
4475 E<gt> 0 if there were C<ierr> switches in the direction of
4476 monotonicity (data still valid).
4477  
4478 =item *
4479  
4480 -1 if C<dim($x, 0) E<lt> 2>.
4481  
4482 =item *
4483  
4484 -3 if C<$x> is not strictly increasing.
4485  
4486 =back
4487  
4488 (The D-array has not been changed in any of these cases.)
4489 NOTE: The above errors are checked in the order listed,
4490 and following arguments have B<NOT> been validated.
4491 EOF
4492 },
4493 Doc => <<'EOF',
4494 =for ref
4495  
4496 Calculate the derivatives of (x,f(x)) using cubic Hermite interpolation.
4497  
4498 Calculate the derivatives needed to determine a monotone piecewise
4499 cubic Hermite interpolant to the given set of points (C<$x,$f>,
4500 where C<$x> is strictly increasing).
4501 The resulting set of points - C<$x,$f,$d>, referred to
4502 as the cubic Hermite representation - can then be used in
4503 other functions, such as L</pchip_chfe>, L</pchip_chfd>,
4504 and L</pchip_chia>.
4505  
4506 The boundary conditions are compatible with monotonicity,
4507 and if the data are only piecewise monotonic, the interpolant
4508 will have an extremum at the switch points; for more control
4509 over these issues use L</pchip_chic>.
4510  
4511 References:
4512  
4513 1. F. N. Fritsch and J. Butland, A method for constructing
4514 local monotone piecewise cubic interpolants, SIAM
4515 Journal on Scientific and Statistical Computing 5, 2
4516 (June 1984), pp. 300-304.
4517  
4518 F. N. Fritsch and R. E. Carlson, Monotone piecewise
4519 cubic interpolation, SIAM Journal on Numerical Analysis
4520 17, 2 (April 1980), pp. 238-246.
4521 EOF
4522 );
4523  
4524 pp_def('pchip_chic',
4525 Pars => 'sbyte ic(two=2); vc(two=2); mflag(); x(n); f(n);
4526 [o]d(n); indx [o]ierr();
4527 [t]h(nless1=CALC($SIZE(n)-1)); [t]slope(nless1);',
4528 GenericTypes => $F,
4529 RedoDimsCode => <<'EOF',
4530 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
4531 EOF
4532 Code => pp_line_numbers(__LINE__, <<'EOF'),
4533 const $GENERIC() d1mach = $TFDE(FLT_EPSILON,DBL_EPSILON,LDBL_EPSILON);
4534 /* VALIDITY-CHECK ARGUMENTS. */
4535 loop (n=1) %{
4536 if ($x() > $x(n=>n-1)) continue;
4537 $ierr() = -1;
4538 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
4539 %}
4540 PDL_Indx ibeg = $ic(two=>0), iend = $ic(two=>1), n = $SIZE(n);
4541 $ierr() = 0;
4542 if (PDL_ABS(ibeg) > 5)
4543 --($ierr());
4544 if (PDL_ABS(iend) > 5)
4545 $ierr() += -2;
4546 if ($ierr() < 0) {
4547 $ierr() += -3;
4548 $CROAK("IC OUT OF RANGE");
4549 }
4550 /* FUNCTION DEFINITION IS OK -- GO ON. */
4551 /* SET UP H AND SLOPE ARRAYS. */
4552 loop (nless1) %{
4553 $h() = $x(n=>nless1+1) - $x(n=>nless1);
4554 $slope() = $f(n=>nless1+1) - $f(n=>nless1);
4555 %}
4556 /* SPECIAL CASE N=2 -- USE LINEAR INTERPOLATION. */
4557 if ($SIZE(nless1) <= 1) {
4558 $d(n=>0) = $d(n=>1) = $slope(nless1=>0);
4559 } else {
4560 /* NORMAL CASE (N .GE. 3) . */
4561 /* SET INTERIOR DERIVATIVES AND DEFAULT END CONDITIONS. */
4562 do { /* inline dpchci */
4563 /* Local variables */
4564 $GENERIC() del1 = $slope(nless1=>0);
4565 /* SPECIAL CASE N=2 is dealt with in separate branch above */
4566 /* NORMAL CASE (N .GE. 3). */
4567 $GENERIC() del2 = $slope(nless1=>1);
4568 /* SET D(1) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */
4569 /* SHAPE-PRESERVING. */
4570 $GENERIC() hsum = $h(nless1=>0) + $h(nless1=>1);
4571 $GENERIC() w1 = ($h(nless1=>0) + hsum) / hsum;
4572 $GENERIC() w2 = -$h(nless1=>0) / hsum;
4573 $d(n=>0) = w1 * del1 + w2 * del2;
4574 if ($PCHST($d(n=>0), del1) <= 0.) {
4575 $d(n=>0) = 0.;
4576 } else if ($PCHST(del1, del2) < 0.) {
4577 /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */
4578 $GENERIC() dmax = 3. * del1;
4579 if (PDL_ABS($d(n=>0)) > PDL_ABS(dmax))
4580 $d(n=>0) = dmax;
4581 }
4582 /* LOOP THROUGH INTERIOR POINTS. */
4583 loop (nless1=1) %{
4584 if (nless1 != 1) {
4585 hsum = $h(nless1=>nless1-1) + $h();
4586 del1 = del2;
4587 del2 = $slope();
4588 }
4589 /* SET D(I)=0 UNLESS DATA ARE STRICTLY MONOTONIC. */
4590 $d(n=>nless1) = 0.;
4591 if ($PCHST(del1, del2) <= 0.)
4592 continue;
4593 /* USE BRODLIE MODIFICATION OF BUTLAND FORMULA. */
4594 $GENERIC() hsumt3 = hsum + hsum + hsum;
4595 w1 = (hsum + $h(nless1=>nless1-1)) / hsumt3;
4596 w2 = (hsum + $h()) / hsumt3;
4597 /* Computing MAX */
4598 $GENERIC() dmax = PDLMAX(PDL_ABS(del1),PDL_ABS(del2));
4599 /* Computing MIN */
4600 $GENERIC() dmin = PDLMIN(PDL_ABS(del1),PDL_ABS(del2));
4601 $GENERIC() drat1 = del1 / dmax, drat2 = del2 / dmax;
4602 $d(n=>nless1) = dmin / (w1 * drat1 + w2 * drat2);
4603 %}
4604 /* SET D(N) VIA NON-CENTERED THREE-POINT FORMULA, ADJUSTED TO BE */
4605 /* SHAPE-PRESERVING. */
4606 w1 = -$h(nless1=>n-2) / hsum;
4607 w2 = ($h(nless1=>n-2) + hsum) / hsum;
4608 $d(n=>n-1) = w1 * del1 + w2 * del2;
4609 if ($PCHST($d(n=>n-1), del2) <= 0.) {
4610 $d(n=>n-1) = 0.;
4611 } else if ($PCHST(del1, del2) < 0.) {
4612 /* NEED DO THIS CHECK ONLY IF MONOTONICITY SWITCHES. */
4613 $GENERIC() dmax = 3. * del2;
4614 if (PDL_ABS($d(n=>n-1)) > PDL_ABS(dmax))
4615 $d(n=>n-1) = dmax;
4616 }
4617 } while (0); /* end inline dpchci */
4618 /* SET DERIVATIVES AT POINTS WHERE MONOTONICITY SWITCHES DIRECTION. */
4619 if ($mflag() != 0.) {
4620 do { /* inline dpchcs */
4621 /* ***PURPOSE Adjusts derivative values for DPCHIC */
4622 /* DPCHCS: DPCHIC Monotonicity Switch Derivative Setter. */
4623 /* Called by DPCHIC to adjust the values of D in the vicinity of a */
4624 /* switch in direction of monotonicity, to produce a more "visually */
4625 /* pleasing" curve than that given by DPCHIM . */
4626 static const $GENERIC() fudge = 4.;
4627 /* Local variables */
4628 PDL_Indx k;
4629 $GENERIC() del[3], fact, dfmx;
4630 $GENERIC() dext, dfloc, slmax, wtave[2];
4631 /* INITIALIZE. */
4632 /* LOOP OVER SEGMENTS. */
4633 loop (nless1=1) %{
4634 $GENERIC() dtmp = $PCHST($slope(nless1=>nless1-1), $slope());
4635 if (dtmp > 0.) {
4636 continue;
4637 }
4638 if (dtmp != 0.) {
4639 /* ....... SLOPE SWITCHES MONOTONICITY AT I-TH POINT ..................... */
4640 /* DO NOT CHANGE D IF 'UP-DOWN-UP'. */
4641 if (nless1 > 1) {
4642 if ($PCHST($slope(nless1=>nless1-2), $slope()) > 0.)
4643 continue;
4644 /* -------------------------- */
4645 }
4646 if (nless1 < $SIZE(nless1)-1 && $PCHST($slope(nless1=>nless1+1), $slope(nless1=>nless1-1)) > 0.)
4647 continue;
4648 /* ---------------------------- */
4649 /* ....... COMPUTE PROVISIONAL VALUE FOR D(1,I). */
4650 dext = $h() / ($h(nless1=>nless1-1) + $h()) * $slope(nless1=>nless1-1) +
4651 $h(nless1=>nless1-1) / ($h(nless1=>nless1-1) + $h()) * $slope();
4652 /* ....... DETERMINE WHICH INTERVAL CONTAINS THE EXTREMUM. */
4653 dtmp = $PCHST(dext, $slope(nless1=>nless1-1));
4654 if (dtmp == 0) {
4655 continue;
4656 }
4657 if (dtmp < 0.) {
4658 /* DEXT AND SLOPE(I-1) HAVE OPPOSITE SIGNS -- */
4659 /* EXTREMUM IS IN (X(I-1),X(I)). */
4660 k = nless1;
4661 /* SET UP TO COMPUTE NEW VALUES FOR D(1,I-1) AND D(1,I). */
4662 wtave[1] = dext;
4663 if (k > 1) {
4664 wtave[0] = $h(nless1=>k-1) / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-2) +
4665 $h(nless1=>k-2) / ($h(nless1=>k-2) + $h(nless1=>k)) * $slope(nless1=>k-1);
4666 }
4667 } else {
4668 /* DEXT AND SLOPE(I) HAVE OPPOSITE SIGNS -- */
4669 /* EXTREMUM IS IN (X(I),X(I+1)). */
4670 k = nless1 + 1;
4671 /* SET UP TO COMPUTE NEW VALUES FOR D(1,I) AND D(1,I+1). */
4672 wtave[0] = dext;
4673 if (k < nless1) {
4674 wtave[1] = $h(nless1=>k) / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k-1) + $h(nless1=>k-1)
4675 / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k);
4676 }
4677 }
4678 } else {
4679 /* ....... AT LEAST ONE OF SLOPE(I-1) AND SLOPE(I) IS ZERO -- */
4680 /* CHECK FOR FLAT-TOPPED PEAK ....................... */
4681 if (nless1 == $SIZE(nless1)-1 || $PCHST($slope(nless1=>nless1-1), $slope(nless1=>nless1+1)) >= 0.)
4682 continue;
4683 /* ----------------------------- */
4684 /* WE HAVE FLAT-TOPPED PEAK ON (X(I),X(I+1)). */
4685 k = nless1+1;
4686 /* SET UP TO COMPUTE NEW VALUES FOR D(1,I) AND D(1,I+1). */
4687 wtave[0] = $h(nless1=>k-1) / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-2) + $h(nless1=>k-2)
4688 / ($h(nless1=>k-2) + $h(nless1=>k-1)) * $slope(nless1=>k-1);
4689 wtave[1] = $h(nless1=>k) / ($h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k-1) + $h(nless1=>k-1) / (
4690 $h(nless1=>k-1) + $h(nless1=>k)) * $slope(nless1=>k);
4691 }
4692 /* ....... AT THIS POINT WE HAVE DETERMINED THAT THERE WILL BE AN EXTREMUM */
4693 /* ON (X(K),X(K+1)), WHERE K=I OR I-1, AND HAVE SET ARRAY WTAVE-- */
4694 /* WTAVE(1) IS A WEIGHTED AVERAGE OF SLOPE(K-1) AND SLOPE(K), */
4695 /* IF K.GT.1 */
4696 /* WTAVE(2) IS A WEIGHTED AVERAGE OF SLOPE(K) AND SLOPE(K+1), */
4697 /* IF K.LT.N-1 */
4698 slmax = PDL_ABS($slope(nless1=>k-1));
4699 if (k > 1) {
4700 /* Computing MAX */
4701 slmax = PDLMAX(slmax,PDL_ABS($slope(nless1=>k-2)));
4702 }
4703 if (k < nless1) {
4704 /* Computing MAX */
4705 slmax = PDLMAX(slmax,PDL_ABS($slope(nless1=>k)));
4706 }
4707 if (k > 1) {
4708 del[0] = $slope(nless1=>k-2) / slmax;
4709 }
4710 del[1] = $slope(nless1=>k-1) / slmax;
4711 if (k < nless1) {
4712 del[2] = $slope(nless1=>k) / slmax;
4713 }
4714 if (k > 1 && k < nless1) {
4715 /* NORMAL CASE -- EXTREMUM IS NOT IN A BOUNDARY INTERVAL. */
4716 fact = fudge * PDL_ABS(del[2] * (del[0] - del[1]) * (wtave[1] / slmax));
4717 $d(n=>k-1) += PDLMIN(fact,1.) * (wtave[0] - $d(n=>k-1));
4718 fact = fudge * PDL_ABS(del[0] * (del[2] - del[1]) * (wtave[0] / slmax));
4719 $d(n=>k) += PDLMIN(fact,1.) * (wtave[1] - $d(n=>k));
4720 } else {
4721 /* SPECIAL CASE K=1 (WHICH CAN OCCUR ONLY IF I=2) OR */
4722 /* K=NLESS1 (WHICH CAN OCCUR ONLY IF I=NLESS1). */
4723 fact = fudge * PDL_ABS(del[1]);
4724 $d(n=>nless1) = PDLMIN(fact,1.) * wtave[nless1+1 - k];
4725 /* NOTE THAT I-K+1 = 1 IF K=I (=NLESS1), */
4726 /* I-K+1 = 2 IF K=I-1(=1). */
4727 }
4728 /* ....... ADJUST IF NECESSARY TO LIMIT EXCURSIONS FROM DATA. */
4729 if ($mflag() <= 0.) {
4730 continue;
4731 }
4732 dfloc = $h(nless1=>k-1) * PDL_ABS($slope(nless1=>k-1));
4733 if (k > 1) {
4734 /* Computing MAX */
4735 dfloc = PDLMAX(dfloc,$h(nless1=>k-2) * PDL_ABS($slope(nless1=>k-2)));
4736 }
4737 if (k < nless1) {
4738 /* Computing MAX */
4739 dfloc = PDLMAX(dfloc,$h(nless1=>k) * PDL_ABS($slope(nless1=>k)));
4740 }
4741 dfmx = $mflag() * dfloc;
4742 PDL_Indx indx = nless1 - k;
4743 /* INDX = 1 IF K=I, 2 IF K=I-1. */
4744 /* --------------------------------------------------------------- */
4745 do { /* inline dpchsw */
4746 /* NOTATION AND GENERAL REMARKS. */
4747 /* RHO IS THE RATIO OF THE DATA SLOPE TO THE DERIVATIVE BEING TESTED. */
4748 /* LAMBDA IS THE RATIO OF D2 TO D1. */
4749 /* THAT = T-HAT(RHO) IS THE NORMALIZED LOCATION OF THE EXTREMUM. */
4750 /* PHI IS THE NORMALIZED VALUE OF P(X)-F1 AT X = XHAT = X-HAT(RHO), */
4751 /* WHERE THAT = (XHAT - X1)/H . */
4752 /* THAT IS, P(XHAT)-F1 = D*H*PHI, WHERE D=D1 OR D2. */
4753 /* SIMILARLY, P(XHAT)-F2 = D*H*(PHI-RHO) . */
4754 /* Local variables */
4755 $GENERIC() cp, nu, phi, rho, hphi, that, sigma, small;
4756 $GENERIC() lambda, radcal;
4757 $GENERIC() d1 = $d(n=>k-1), d2 = $d(n=>k), h2 = $h(nless1=>k-1), slope2 = $slope(nless1=>k-1);
4758 /* Initialized data */
4759 static const $GENERIC() fact = 100.;
4760 /* THIRD SHOULD BE SLIGHTLY LESS THAN 1/3. */
4761 static const $GENERIC() third = .33333;
4762 /* SMALL SHOULD BE A FEW ORDERS OF MAGNITUDE GREATER THAN MACHEPS. */
4763 small = fact * d1mach;
4764 /* DO MAIN CALCULATION. */
4765 if (d1 == 0.) {
4766 /* SPECIAL CASE -- D1.EQ.ZERO . */
4767 /* IF D2 IS ALSO ZERO, THIS ROUTINE SHOULD NOT HAVE BEEN CALLED. */
4768 if (d2 == 0.) {
4769 $ierr() = -1;
4770 $CROAK("D1 AND/OR D2 INVALID");
4771 }
4772 rho = slope2 / d2;
4773 /* EXTREMUM IS OUTSIDE INTERVAL WHEN RHO .GE. 1/3 . */
4774 if (rho >= third) {
4775 $ierr() = 0; break;
4776 }
4777 that = 2. * (3. * rho - 1.) / (3. * (2. * rho - 1.));
4778 /* Computing 2nd power */
4779 phi = that * that * ((3. * rho - 1.) / 3.);
4780 /* CONVERT TO DISTANCE FROM F2 IF IEXTRM.NE.1 . */
4781 if (indx != 3) {
4782 phi -= rho;
4783 }
4784 /* TEST FOR EXCEEDING LIMIT, AND ADJUST ACCORDINGLY. */
4785 hphi = h2 * PDL_ABS(phi);
4786 if (hphi * PDL_ABS(d2) > dfmx) {
4787 /* AT THIS POINT, HPHI.GT.0, SO DIVIDE IS OK. */
4788 d2 = $SIGN(dfmx / hphi, d2);
4789 }
4790 } else {
4791 rho = slope2 / d1;
4792 lambda = -(d2) / d1;
4793 if (d2 == 0.) {
4794 /* SPECIAL CASE -- D2.EQ.ZERO . */
4795 /* EXTREMUM IS OUTSIDE INTERVAL WHEN RHO .GE. 1/3 . */
4796 if (rho >= third) {
4797 $ierr() = 0; break;
4798 }
4799 cp = 2. - 3. * rho;
4800 nu = 1. - 2. * rho;
4801 that = 1. / (3. * nu);
4802 } else {
4803 if (lambda <= 0.) {
4804 $ierr() = -1;
4805 $CROAK("D1 AND/OR D2 INVALID");
4806 }
4807 /* NORMAL CASE -- D1 AND D2 BOTH NONZERO, OPPOSITE SIGNS. */
4808 nu = 1. - lambda - 2. * rho;
4809 sigma = 1. - rho;
4810 cp = nu + sigma;
4811 if (PDL_ABS(nu) > small) {
4812 /* Computing 2nd power */
4813 radcal = (nu - (2. * rho + 1.)) * nu + sigma * sigma;
4814 if (radcal < 0.) {
4815 $ierr() = -2;
4816 $CROAK("NEGATIVE RADICAL");
4817 }
4818 that = (cp - sqrt(radcal)) / (3. * nu);
4819 } else {
4820 that = 1. / (2. * sigma);
4821 }
4822 }
4823 phi = that * ((nu * that - cp) * that + 1.);
4824 /* CONVERT TO DISTANCE FROM F2 IF IEXTRM.NE.1 . */
4825 if (indx != 3) {
4826 phi -= rho;
4827 }
4828 /* TEST FOR EXCEEDING LIMIT, AND ADJUST ACCORDINGLY. */
4829 hphi = h2 * PDL_ABS(phi);
4830 if (hphi * PDL_ABS(d1) > dfmx) {
4831 /* AT THIS POINT, HPHI.GT.0, SO DIVIDE IS OK. */
4832 d1 = $SIGN(dfmx / hphi, d1);
4833 d2 = -lambda * d1;
4834 }
4835 }
4836 $ierr() = 0;
4837 } while (0); /* end inline dpchsw */
4838 /* --------------------------------------------------------------- */
4839 if ($ierr() != 0) {
4840 break;
4841 }
4842 %} /* ....... END OF SEGMENT LOOP. */
4843 } while (0); /* end inline dpchcs */
4844 }
4845 }
4846 /* SET END CONDITIONS. */
4847 if (ibeg == 0 && iend == 0)
4848 continue;
4849 /* ------------------------------------------------------- */
4850 do { /* inline dpchce */
4851 /* Local variables */
4852 PDL_Indx j, k, ibeg = $ic(two=>0), iend = $ic(two=>1);
4853 $GENERIC() stemp[3], xtemp[4];
4854 /* SET TO DEFAULT BOUNDARY CONDITIONS IF N IS TOO SMALL. */
4855 if (PDL_ABS(ibeg) > n)
4856 ibeg = 0;
4857 if (PDL_ABS(iend) > n)
4858 iend = 0;
4859 /* TREAT BEGINNING BOUNDARY CONDITION. */
4860 if (ibeg != 0) {
4861 k = PDL_ABS(ibeg);
4862 if (k == 1) {
4863 /* BOUNDARY VALUE PROVIDED. */
4864 $d(n=>0) = $vc(two=>0);
4865 } else if (k == 2) {
4866 /* BOUNDARY SECOND DERIVATIVE PROVIDED. */
4867 $d(n=>0) = 0.5 * (3. * $slope(nless1=>0) - $d(n=>1) - 0.5 * $vc(two=>0) * $h(nless1=>0));
4868 } else if (k < 5) {
4869 /* USE K-POINT DERIVATIVE FORMULA. */
4870 /* PICK UP FIRST K POINTS, IN REVERSE ORDER. */
4871 for (j = 0; j < k; ++j) {
4872 PDL_Indx index = k - j;
4873 /* INDEX RUNS FROM K DOWN TO 1. */
4874 xtemp[j] = $x(n=>index+1);
4875 if (j < k-1) {
4876 stemp[j] = $slope(nless1=>index);
4877 }
4878 }
4879 /* ----------------------------- */
4880 $PCHDF(k, xtemp, stemp, $d(n=>0));
4881 /* ----------------------------- */
4882 } else {
4883 /* USE 'NOT A KNOT' CONDITION. */
4884 $d(n=>0) = (3. * ($h(nless1=>0) * $slope(nless1=>1) + $h(nless1=>1) * $slope(nless1=>0)) -
4885 2. * ($h(nless1=>0) + $h(nless1=>1)) * $d(n=>1) - $h(nless1=>0) * $d(n=>2)) / $h(nless1=>1);
4886 }
4887 /* CHECK D(1,1) FOR COMPATIBILITY WITH MONOTONICITY. */
4888 if (ibeg <= 0) {
4889 if ($slope(nless1=>0) == 0.) {
4890 if ($d(n=>0) != 0.) {
4891 $d(n=>0) = 0.;
4892 ++($ierr());
4893 }
4894 } else if ($PCHST($d(n=>0), $slope(nless1=>0)) < 0.) {
4895 $d(n=>0) = 0.;
4896 ++($ierr());
4897 } else if (PDL_ABS($d(n=>0)) > 3. * PDL_ABS($slope(nless1=>0))) {
4898 $d(n=>0) = 3. * $slope(nless1=>0);
4899 ++($ierr());
4900 }
4901 }
4902 }
4903 /* TREAT END BOUNDARY CONDITION. */
4904 if (iend == 0)
4905 break;
4906 k = PDL_ABS(iend);
4907 if (k == 1) {
4908 /* BOUNDARY VALUE PROVIDED. */
4909 $d(n=>n-1) = $vc(two=>1);
4910 } else if (k == 2) {
4911 /* BOUNDARY SECOND DERIVATIVE PROVIDED. */
4912 $d(n=>n-1) = 0.5 * (3. * $slope(nless1=>n-2) - $d(n=>n-2)
4913 + 0.5 * $vc(two=>1) * $h(nless1=>n-2));
4914 } else if (k < 5) {
4915 /* USE K-POINT DERIVATIVE FORMULA. */
4916 /* PICK UP LAST K POINTS. */
4917 for (j = 0; j < k; ++j) {
4918 PDL_Indx index = n - k + j;
4919 /* INDEX RUNS FROM N+1-K UP TO N. */
4920 xtemp[j] = $x(n=>index);
4921 if (j < k-1) {
4922 stemp[j] = $slope(nless1=>index);
4923 }
4924 }
4925 /* ----------------------------- */
4926 $PCHDF(k, xtemp, stemp, $d(n=>n-1));
4927 /* ----------------------------- */
4928 } else {
4929 /* USE 'NOT A KNOT' CONDITION. */
4930 $d(n=>n-1) = (3. * ($h(nless1=>n-2) * $slope(nless1=>n-3) +
4931 $h(nless1=>n-3) * $slope(nless1=>n-2)) - 2. * ($h(nless1=>n-2) + $h(nless1=>n-3)) *
4932 $d(n=>n-2) - $h(nless1=>n-2) * $d(n=>n-3)) / $h(nless1=>n-3);
4933 }
4934 if (iend > 0)
4935 break;
4936 /* CHECK D(1,N) FOR COMPATIBILITY WITH MONOTONICITY. */
4937 if ($slope(nless1=>n-2) == 0.) {
4938 if ($d(n=>n-1) != 0.) {
4939 $d(n=>n-1) = 0.;
4940 $ierr() += 2;
4941 }
4942 } else if ($PCHST($d(n=>n-1), $slope(nless1=>n-2)) < 0.) {
4943 $d(n=>n-1) = 0.;
4944 $ierr() += 2;
4945 } else if (PDL_ABS($d(n=>n-1)) > 3. * PDL_ABS($slope(nless1=>n-2))) {
4946 $d(n=>n-1) = 3. * $slope(nless1=>n-2);
4947 $ierr() += 2;
4948 }
4949 } while (0); /* end inlined dpchce */
4950 /* ------------------------------------------------------- */
4951 EOF
4952 ParamDesc => {
4953 ic => <<'EOF',
4954 The first and second elements of C<$ic> determine the boundary
4955 conditions at the start and end of the data respectively.
4956 If the value is 0, then the default condition, as used by
4957 L</pchip_chim>, is adopted.
4958 If greater than zero, no adjustment for monotonicity is made,
4959 otherwise if less than zero the derivative will be adjusted.
4960 The allowed magnitudes for C<ic(0)> are:
4961  
4962 =over
4963  
4964 =item *
4965  
4966 1 if first derivative at C<x(0)> is given in C<vc(0)>.
4967  
4968 =item *
4969  
4970 2 if second derivative at C<x(0)> is given in C<vc(0)>.
4971  
4972 =item *
4973  
4974 3 to use the 3-point difference formula for C<d(0)>.
4975 (Reverts to the default b.c. if C<n E<lt> 3>)
4976  
4977 =item *
4978  
4979 4 to use the 4-point difference formula for C<d(0)>.
4980 (Reverts to the default b.c. if C<n E<lt> 4>)
4981  
4982 =item *
4983  
4984 5 to set C<d(0)> so that the second derivative is
4985 continuous at C<x(1)>.
4986 (Reverts to the default b.c. if C<n E<lt> 4>)
4987 This option is somewhat analogous to the "not a knot"
4988 boundary condition provided by DPCHSP.
4989  
4990 =back
4991  
4992 The values for C<ic(1)> are the same as above, except that
4993 the first-derivative value is stored in C<vc(1)> for cases 1 and 2.
4994 The values of C<$vc> need only be set if options 1 or 2 are chosen
4995 for C<$ic>. NOTES:
4996  
4997 =over
4998  
4999 =item *
5000  
5001 Only in case C<$ic(n)> E<lt> 0 is it guaranteed that the interpolant
5002 will be monotonic in the first interval. If the returned value of
5003 D(start_or_end) lies between zero and 3*SLOPE(start_or_end), the
5004 interpolant will be monotonic. This is B<NOT> checked if C<$ic(n)>
5005 E<gt> 0.
5006  
5007 =item *
5008  
5009 If C<$ic(n)> E<lt> 0 and D(0) had to be changed to achieve monotonicity,
5010 a warning error is returned.
5011  
5012 =back
5013  
5014 Set C<$mflag = 0> if interpolant is required to be monotonic in
5015 each interval, regardless of monotonicity of data. This causes C<$d> to be
5016 set to 0 at all switch points. NOTES:
5017  
5018 =over
5019  
5020 =item *
5021  
5022 This will cause D to be set to zero at all switch points, thus
5023 forcing extrema there.
5024  
5025 =item *
5026  
5027 The result of using this option with the default boundary conditions
5028 will be identical to using DPCHIM, but will generally cost more
5029 compute time. This option is provided only to facilitate comparison
5030 of different switch and/or boundary conditions.
5031  
5032 =back
5033 EOF
5034 vc => 'See ic for details',
5035 mflag => <<'EOF',
5036 Set to non-zero to
5037 use a formula based on the 3-point difference formula at switch
5038 points. If C<$mflag E<gt> 0>, then the interpolant at switch points
5039 is forced to not deviate from the data by more than C<$mflag*dfloc>,
5040 where C<dfloc> is the maximum of the change of C<$f> on this interval
5041 and its two immediate neighbours.
5042 If C<$mflag E<lt> 0>, no such control is to be imposed.
5043 EOF
5044 x => <<'EOF',
5045 array of independent variable values. The
5046 elements of X must be strictly increasing:
5047  
5048 X(I-1) .LT. X(I), I = 2(1)N.
5049  
5050 (Error return if not.)
5051 EOF
5052 f => <<'EOF',
5053 array of dependent variable values to be
5054 interpolated. F(I) is value corresponding to X(I).
5055 EOF
5056 d => <<'EOF',
5057 array of derivative values at the data
5058 points. These values will determine a monotone cubic
5059 Hermite function on each subinterval on which the data
5060 are monotonic, except possibly adjacent to switches in
5061 monotonicity. The value corresponding to X(I) is stored in D(I).
5062 No other entries in D are changed.
5063 EOF
5064 ierr => <<'EOF',
5065 Error status:
5066  
5067 =over
5068  
5069 =item *
5070  
5071 0 if successful.
5072  
5073 =item *
5074  
5075 1 if C<ic(0) E<lt> 0> and C<d(0)> had to be adjusted for
5076 monotonicity.
5077  
5078 =item *
5079  
5080 2 if C<ic(1) E<lt> 0> and C<d(n-1)> had to be adjusted
5081 for monotonicity.
5082  
5083 =item *
5084  
5085 3 if both 1 and 2 are true.
5086  
5087 =item *
5088  
5089 -1 if C<n E<lt> 2>.
5090  
5091 =item *
5092  
5093 -3 if C<$x> is not strictly increasing.
5094  
5095 =item *
5096  
5097 -4 if C<abs(ic(0)) E<gt> 5>.
5098  
5099 =item *
5100  
5101 -5 if C<abs(ic(1)) E<gt> 5>.
5102  
5103 =item *
5104  
5105 -6 if both -4 and -5 are true.
5106  
5107 =item *
5108  
5109 -7 if C<nwk E<lt> 2*(n-1)>.
5110  
5111 =back
5112  
5113 (The D-array has not been changed in any of these cases.)
5114 NOTE: The above errors are checked in the order listed,
5115 and following arguments have B<NOT> been validated.
5116 EOF
5117 },
5118 Doc => <<'EOF',
5119 =for ref
5120  
5121 Set derivatives needed to determine a piecewise monotone piecewise
5122 cubic Hermite interpolant to given data. User control is available
5123 over boundary conditions and/or treatment of points where monotonicity
5124 switches direction.
5125  
5126 Calculate the derivatives needed to determine a piecewise monotone piecewise
5127 cubic interpolant to the data given in (C<$x,$f>,
5128 where C<$x> is strictly increasing).
5129 Control over the boundary conditions is given by the
5130 C<$ic> and C<$vc> ndarrays, and the value of C<$mflag> determines
5131 the treatment of points where monotonicity switches
5132 direction. A simpler, more restricted, interface is available
5133 using L</pchip_chim>.
5134 The resulting piecewise cubic Hermite function may be evaluated
5135 by L</pchip_chfe> or L</pchip_chfd>.
5136  
5137 References:
5138  
5139 1. F. N. Fritsch, Piecewise Cubic Hermite Interpolation
5140 Package, Report UCRL-87285, Lawrence Livermore National
5141 Laboratory, July 1982. [Poster presented at the
5142 SIAM 30th Anniversary Meeting, 19-23 July 1982.]
5143  
5144 2. F. N. Fritsch and J. Butland, A method for constructing
5145 local monotone piecewise cubic interpolants, SIAM
5146 Journal on Scientific and Statistical Computing 5, 2
5147 (June 1984), pp. 300-304.
5148  
5149 3. F. N. Fritsch and R. E. Carlson, Monotone piecewise
5150 cubic interpolation, SIAM Journal on Numerical
5151 Analysis 17, 2 (April 1980), pp. 238-246.
5152 EOF
5153 );
5154  
5155 pp_def('pchip_chsp',
5156 Pars => 'sbyte ic(two=2); vc(two=2); x(n); f(n);
5157 [o]d(n); indx [o]ierr();
5158 [t]dx(n); [t]dy_dx(n);
5159 ',
5160 GenericTypes => $F,
5161 RedoDimsCode => <<'EOF',
5162 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
5163 EOF
5164 Code => pp_line_numbers(__LINE__, <<'EOF'),
5165 /* SINGULAR SYSTEM. */
5166 /* *** THEORETICALLY, THIS CAN ONLY OCCUR IF SUCCESSIVE X-VALUES *** */
5167 /* *** ARE EQUAL, WHICH SHOULD ALREADY HAVE BEEN CAUGHT (IERR=-3). *** */
5168 #define dpchsp_singular(x, ind) \
5169 $ierr() = -8; $CROAK("SINGULAR LINEAR SYSTEM(" #x ") at %td", ind);
5170 /* Local variables */
5171 $GENERIC() stemp[3], xtemp[4];
5172 PDL_Indx n = $SIZE(n), nm1 = n - 1;
5173 /* VALIDITY-CHECK ARGUMENTS. */
5174 loop (n=1) %{
5175 if ($x() > $x(n=>n-1)) continue;
5176 $ierr() = -1;
5177 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
5178 %}
5179 PDL_Indx ibeg = $ic(two=>0), iend = $ic(two=>1), j;
5180 $ierr() = 0;
5181 if (PDL_ABS(ibeg) > 5)
5182 --($ierr());
5183 if (PDL_ABS(iend) > 5)
5184 $ierr() += -2;
5185 if ($ierr() < 0) {
5186 $ierr() += -3;
5187 $CROAK("IC OUT OF RANGE");
5188 }
5189 /* FUNCTION DEFINITION IS OK -- GO ON. */
5190 /* COMPUTE FIRST DIFFERENCES OF X SEQUENCE AND STORE IN WK(1,.). ALSO, */
5191 /* COMPUTE FIRST DIVIDED DIFFERENCE OF DATA AND STORE IN WK(2,.). */
5192 loop (n=1) %{
5193 $dx() = $x() - $x(n=>n-1);
5194 $dy_dx() = ($f() - $f(n=>n-1)) / $dx();
5195 %}
5196 /* SET TO DEFAULT BOUNDARY CONDITIONS IF N IS TOO SMALL. */
5197 if (ibeg > n) {
5198 ibeg = 0;
5199 }
5200 if (iend > n) {
5201 iend = 0;
5202 }
5203 /* SET UP FOR BOUNDARY CONDITIONS. */
5204 if (ibeg == 1 || ibeg == 2) {
5205 $d(n=>0) = $vc(two=>0);
5206 } else if (ibeg > 2) {
5207 /* PICK UP FIRST IBEG POINTS, IN REVERSE ORDER. */
5208 for (j = 0; j < ibeg; ++j) {
5209 PDL_Indx index = ibeg - j + 1;
5210 /* INDEX RUNS FROM IBEG DOWN TO 1. */
5211 xtemp[j] = $x(n=>index);
5212 if (j < ibeg-1)
5213 stemp[j] = $dy_dx(n=>index);
5214 }
5215 /* -------------------------------- */
5216 $PCHDF(ibeg, xtemp, stemp, $d(n=>0));
5217 /* -------------------------------- */
5218 ibeg = 1;
5219 }
5220 if (iend == 1 || iend == 2) {
5221 $d(n=>n-1) = $vc(two=>1);
5222 } else if (iend > 2) {
5223 /* PICK UP LAST IEND POINTS. */
5224 for (j = 0; j < iend; ++j) {
5225 PDL_Indx index = n - iend + j;
5226 /* INDEX RUNS FROM N+1-IEND UP TO N. */
5227 xtemp[j] = $x(n=>index);
5228 if (j < iend-1)
5229 stemp[j] = $dy_dx(n=>index+1);
5230 }
5231 /* -------------------------------- */
5232 $PCHDF(iend, xtemp, stemp, $d(n=>n-1));
5233 /* -------------------------------- */
5234 iend = 1;
5235 }
5236 /* --------------------( BEGIN CODING FROM CUBSPL )-------------------- */
5237 /* **** A TRIDIAGONAL LINEAR SYSTEM FOR THE UNKNOWN SLOPES S(J) OF */
5238 /* F AT X(J), J=1,...,N, IS GENERATED AND THEN SOLVED BY GAUSS ELIM- */
5239 /* INATION, WITH S(J) ENDING UP IN D(1,J), ALL J. */
5240 /* WK(1,.) AND WK(2,.) ARE USED FOR TEMPORARY STORAGE. */
5241 /* CONSTRUCT FIRST EQUATION FROM FIRST BOUNDARY CONDITION, OF THE FORM */
5242 /* WK(2,1)*S(1) + WK(1,1)*S(2) = D(1,1) */
5243 if (ibeg == 0) {
5244 if (n == 2) {
5245 /* NO CONDITION AT LEFT END AND N = 2. */
5246 $dy_dx(n=>0) = 1.;
5247 $dx(n=>0) = 1.;
5248 $d(n=>0) = 2. * $dy_dx(n=>1);
5249 } else {
5250 /* NOT-A-KNOT CONDITION AT LEFT END AND N .GT. 2. */
5251 $dy_dx(n=>0) = $dx(n=>2);
5252 $dx(n=>0) = $dx(n=>1) + $dx(n=>2);
5253 /* Computing 2nd power */
5254 $d(n=>0) = (($dx(n=>1) + 2. * $dx(n=>0)) * $dy_dx(n=>1) * $dx(n=>2) + $dx(n=>1) *
5255 $dx(n=>1) * $dy_dx(n=>2)) / $dx(n=>0);
5256 }
5257 } else if (ibeg == 1) {
5258 /* SLOPE PRESCRIBED AT LEFT END. */
5259 $dy_dx(n=>0) = 1.;
5260 $dx(n=>0) = 0.;
5261 } else {
5262 /* SECOND DERIVATIVE PRESCRIBED AT LEFT END. */
5263 $dy_dx(n=>0) = 2.;
5264 $dx(n=>0) = 1.;
5265 $d(n=>0) = 3. * $dy_dx(n=>1) - 0.5 * $dx(n=>1) * $d(n=>0);
5266 }
5267 /* IF THERE ARE INTERIOR KNOTS, GENERATE THE CORRESPONDING EQUATIONS AND */
5268 /* CARRY OUT THE FORWARD PASS OF GAUSS ELIMINATION, AFTER WHICH THE J-TH */
5269 /* EQUATION READS WK(2,J)*S(J) + WK(1,J)*S(J+1) = D(1,J). */
5270 if (n > 2) {
5271 loop (n=1:-1) %{
5272 if ($dy_dx(n=>n-1) == 0.) {
5273 dpchsp_singular(1, n-1);
5274 }
5275 $GENERIC() g = -$dx(n=>n+1) / $dy_dx(n=>n-1);
5276 $d() = g * $d(n=>n-1) + 3. * ($dx() * $dy_dx(n=>n+1) +
5277 $dx(n=>n+1) * $dy_dx());
5278 $dy_dx() = g * $dx(n=>n-1) + 2. * ($dx() + $dx(n=>n+1));
5279 %}
5280 }
5281 /* CONSTRUCT LAST EQUATION FROM SECOND BOUNDARY CONDITION, OF THE FORM */
5282 /* (-G*WK(2,N-1))*S(N-1) + WK(2,N)*S(N) = D(1,N) */
5283 /* IF SLOPE IS PRESCRIBED AT RIGHT END, ONE CAN GO DIRECTLY TO BACK- */
5284 /* SUBSTITUTION, SINCE ARRAYS HAPPEN TO BE SET UP JUST RIGHT FOR IT */
5285 /* AT THIS POINT. */
5286 if (iend != 1) {
5287 if (iend == 0 && n == 2 && ibeg == 0) {
5288 /* NOT-A-KNOT AT RIGHT ENDPOINT AND AT LEFT ENDPOINT AND N = 2. */
5289 $d(n=>1) = $dy_dx(n=>1);
5290 } else {
5291 $GENERIC() g;
5292 if (iend == 0) {
5293 if (n == 2 || (n == 3 && ibeg == 0)) {
5294 /* EITHER (N=3 AND NOT-A-KNOT ALSO AT LEFT) OR (N=2 AND *NOT* */
5295 /* NOT-A-KNOT AT LEFT END POINT). */
5296 $d(n=>n-1) = 2. * $dy_dx(n=>n-1);
5297 $dy_dx(n=>n-1) = 1.;
5298 if ($dy_dx(n=>n-2) == 0.) {
5299 dpchsp_singular(2, n-2);
5300 }
5301 g = -1. / $dy_dx(n=>n-2);
5302 } else {
5303 /* NOT-A-KNOT AND N .GE. 3, AND EITHER N.GT.3 OR ALSO NOT-A- */
5304 /* KNOT AT LEFT END POINT. */
5305 g = $dx(n=>n-2) + $dx(n=>n-1);
5306 /* DO NOT NEED TO CHECK FOLLOWING DENOMINATORS (X-DIFFERENCES). */
5307 /* Computing 2nd power */
5308 $GENERIC() dtmp = $dx(n=>n-1);
5309 $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;
5310 if ($dy_dx(n=>n-2) == 0.) {
5311 dpchsp_singular(3, n-2);
5312 }
5313 g /= -$dy_dx(n=>n-2);
5314 $dy_dx(n=>n-1) = $dx(n=>n-2);
5315 }
5316 } else {
5317 /* SECOND DERIVATIVE PRESCRIBED AT RIGHT ENDPOINT. */
5318 $d(n=>n-1) = 3. * $dy_dx(n=>n-1) + 0.5 * $dx(n=>n-1) * $d(n=>n-1);
5319 $dy_dx(n=>n-1) = 2.;
5320 if ($dy_dx(n=>n-2) == 0.) {
5321 dpchsp_singular(4, n-2);
5322 }
5323 g = -1. / $dy_dx(n=>n-2);
5324 }
5325 /* COMPLETE FORWARD PASS OF GAUSS ELIMINATION. */
5326 $dy_dx(n=>n-1) = g * $dx(n=>n-2) + $dy_dx(n=>n-1);
5327 if ($dy_dx(n=>n-1) == 0.) {
5328 dpchsp_singular(5, n-1);
5329 }
5330 $d(n=>n-1) = (g * $d(n=>n-2) + $d(n=>n-1)) / $dy_dx(n=>n-1);
5331 }
5332 }
5333 /* CARRY OUT BACK SUBSTITUTION */
5334 loop (n=nm1-1::-1) %{
5335 if ($dy_dx() == 0.) {
5336 dpchsp_singular(6, n);
5337 }
5338 $d() = ($d() - $dx() * $d(n=>n+1)) / $dy_dx();
5339 %}
5340 /* --------------------( END CODING FROM CUBSPL )-------------------- */
5341 #undef dpchsp_singular
5342 EOF
5343 ParamDesc => {
5344 ic => <<'EOF',
5345 The first and second elements determine the boundary
5346 conditions at the start and end of the data respectively.
5347 The allowed values for C<ic(0)> are:
5348  
5349 =over
5350  
5351 =item *
5352  
5353 0 to set C<d(0)> so that the third derivative is
5354 continuous at C<x(1)>.
5355  
5356 =item *
5357  
5358 1 if first derivative at C<x(0)> is given in C<vc(0>).
5359  
5360 =item *
5361  
5362 2 if second derivative at C<x(0>) is given in C<vc(0)>.
5363  
5364 =item *
5365  
5366 3 to use the 3-point difference formula for C<d(0)>.
5367 (Reverts to the default b.c. if C<n E<lt> 3>.)
5368  
5369 =item *
5370  
5371 4 to use the 4-point difference formula for C<d(0)>.
5372 (Reverts to the default b.c. if C<n E<lt> 4>.)
5373  
5374 =back
5375  
5376 The values for C<ic(1)> are the same as above, except that
5377 the first-derivative value is stored in C<vc(1)> for cases 1 and 2.
5378 The values of C<$vc> need only be set if options 1 or 2 are chosen
5379 for C<$ic>.
5380  
5381 NOTES: For the "natural" boundary condition, use IC(n)=2 and VC(n)=0.
5382 EOF
5383 vc => 'See ic for details',
5384 ierr => <<'EOF',
5385 Error status:
5386  
5387 =over
5388  
5389 =item *
5390  
5391 0 if successful.
5392  
5393 =item *
5394  
5395 -1 if C<dim($x, 0) E<lt> 2>.
5396  
5397 =item *
5398  
5399 -3 if C<$x> is not strictly increasing.
5400  
5401 =item *
5402  
5403 -4 if C<ic(0) E<lt> 0> or C<ic(0) E<gt> 4>.
5404  
5405 =item *
5406  
5407 -5 if C<ic(1) E<lt> 0> or C<ic(1) E<gt> 4>.
5408  
5409 =item *
5410  
5411 -6 if both of the above are true.
5412  
5413 =item *
5414  
5415 -7 if C<nwk E<lt> 2*n>.
5416  
5417 NOTE: The above errors are checked in the order listed,
5418 and following arguments have B<NOT> been validated.
5419 (The D-array has not been changed in any of these cases.)
5420  
5421 =item *
5422  
5423 -8 in case of trouble solving the linear system
5424 for the interior derivative values.
5425 (The D-array may have been changed in this case. Do B<NOT> use it!)
5426  
5427 =back
5428 EOF
5429 },
5430 Doc => <<'EOF',
5431 =for ref
5432  
5433 Calculate the derivatives of (x,f(x)) using cubic spline interpolation.
5434  
5435 Computes the Hermite representation of the cubic spline interpolant
5436 to the data given in (C<$x,$f>), with the specified boundary conditions.
5437 Control over the boundary conditions is given by the
5438 C<$ic> and C<$vc> ndarrays.
5439 The resulting values - C<$x,$f,$d> - can
5440 be used in all the functions which expect a cubic
5441 Hermite function, including L</pchip_bvalu>.
5442  
5443 References: Carl de Boor, A Practical Guide to Splines, Springer-Verlag,
5444 New York, 1978, pp. 53-59.
5445 EOF
5446 );
5447  
5448 pp_def('pchip_chfd',
5449 Pars => 'x(n); f(n); d(n); xe(ne);
5450 [o] fe(ne); [o] de(ne); indx [o] ierr(); int [o] skip()',
5451 RedoDimsCode => <<'EOF',
5452 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
5453 if ($SIZE(ne) < 1) $CROAK("NUMBER OF EVALUATION POINTS LESS THAN ONE");
5454 EOF
5455 Code => pp_line_numbers(__LINE__, <<'EOF'),
5456 $CHFD(1);
5457 EOF
5458 GenericTypes => $F,
5459 ParamDesc => {
5460 skip => <<'EOF',
5461 Set to 1 to skip checks on the input data.
5462 This will save time in case these checks have already
5463 been performed (say, in L</pchip_chim> or L</pchip_chic>).
5464 Will be set to TRUE on normal return.
5465 EOF
5466 xe => <<'EOF',
5467 array of points at which the functions are to
5468 be evaluated. NOTES:
5469  
5470 =over
5471  
5472 =item 1
5473  
5474 The evaluation will be most efficient if the elements
5475 of XE are increasing relative to X;
5476 that is, XE(J) .GE. X(I)
5477 implies XE(K) .GE. X(I), all K.GE.J .
5478  
5479 =item 2
5480  
5481 If any of the XE are outside the interval [X(1),X(N)],
5482 values are extrapolated from the nearest extreme cubic,
5483 and a warning error is returned.
5484  
5485 =back
5486 EOF
5487 fe => <<'EOF',
5488 array of values of the cubic Hermite
5489 function defined by N, X, F, D at the points XE.
5490 EOF
5491 de => <<'EOF',
5492 array of values of the first derivative of the same function at the points XE.
5493 EOF
5494 ierr => <<'EOF',
5495 Error status:
5496  
5497 =over
5498  
5499 =item *
5500  
5501 0 if successful.
5502  
5503 =item *
5504  
5505 E<gt>0 if extrapolation was performed at C<ierr> points
5506 (data still valid).
5507  
5508 =item *
5509  
5510 -1 if C<dim($x, 0) E<lt> 2>
5511  
5512 =item *
5513  
5514 -3 if C<$x> is not strictly increasing.
5515  
5516 =item *
5517  
5518 -4 if C<dim($xe, 0) E<lt> 1>.
5519  
5520 =item *
5521  
5522 -5 if an error has occurred in a lower-level routine,
5523 which should never happen.
5524  
5525 =back
5526 EOF
5527 },
5528 Doc => <<'EOF',
5529 =for ref
5530  
5531 Evaluate a piecewise cubic Hermite function and its first derivative
5532 at an array of points. May be used by itself for Hermite interpolation,
5533 or as an evaluator for DPCHIM or DPCHIC.
5534  
5535 Given a piecewise cubic Hermite function - such as from
5536 L</pchip_chim> - evaluate the function (C<$fe>) and
5537 derivative (C<$de>) at a set of points (C<$xe>).
5538 If function values alone are required, use L</pchip_chfe>.
5539 EOF
5540 );
5541  
5542 pp_def('pchip_chfe',
5543 Pars => 'x(n); f(n); d(n); xe(ne);
5544 [o] fe(ne); indx [o] ierr(); int [o] skip()',
5545 RedoDimsCode => <<'EOF',
5546 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
5547 if ($SIZE(ne) < 1) $CROAK("NUMBER OF EVALUATION POINTS LESS THAN ONE");
5548 EOF
5549 Code => pp_line_numbers(__LINE__, <<'EOF'),
5550 $CHFD(0);
5551 EOF
5552 GenericTypes => $F,
5553 ParamDesc => {
5554 x => <<'EOF',
5555 array of independent variable values. The
5556 elements of X must be strictly increasing:
5557  
5558 X(I-1) .LT. X(I), I = 2(1)N.
5559  
5560 (Error return if not.)
5561 EOF
5562 f => <<'EOF',
5563 array of function values. F(I) is the value corresponding to X(I).
5564 EOF
5565 d => <<'EOF',
5566 array of derivative values. D(I) is the value corresponding to X(I).
5567 EOF
5568 skip => <<'EOF',
5569 Set to 1 to skip checks on the input data.
5570 This will save time in case these checks have already
5571 been performed (say, in L</pchip_chim> or L</pchip_chic>).
5572 Will be set to TRUE on normal return.
5573 EOF
5574 xe => <<'EOF',
5575 array of points at which the function is to be evaluated. NOTES:
5576  
5577 =over
5578  
5579 =item 1
5580  
5581 The evaluation will be most efficient if the elements
5582 of XE are increasing relative to X;
5583 that is, XE(J) .GE. X(I)
5584 implies XE(K) .GE. X(I), all K.GE.J .
5585  
5586 =item 2
5587  
5588 If any of the XE are outside the interval [X(1),X(N)],
5589 values are extrapolated from the nearest extreme cubic,
5590 and a warning error is returned.
5591  
5592 =back
5593 EOF
5594 fe => <<'EOF',
5595 array of values of the cubic Hermite
5596 function defined by N, X, F, D at the points XE.
5597 EOF
5598 ierr => <<'EOF',
5599 Error status returned by C<$>:
5600  
5601 =over
5602  
5603 =item *
5604  
5605 0 if successful.
5606  
5607 =item *
5608  
5609 E<gt>0 if extrapolation was performed at C<ierr> points
5610 (data still valid).
5611  
5612 =item *
5613  
5614 -1 if C<dim($x, 0) E<lt> 2>
5615  
5616 =item *
5617  
5618 -3 if C<$x> is not strictly increasing.
5619  
5620 =item *
5621  
5622 -4 if C<dim($xe, 0) E<lt> 1>.
5623  
5624 =back
5625  
5626 (The FE-array has not been changed in any of these cases.)
5627 NOTE: The above errors are checked in the order listed,
5628 and following arguments have B<NOT> been validated.
5629 EOF
5630 },
5631 Doc => <<'EOF',
5632 =for ref
5633  
5634 Evaluate a piecewise cubic Hermite function at an array of points.
5635 May be used by itself for Hermite interpolation, or as an evaluator
5636 for L</pchip_chim> or L</pchip_chic>.
5637  
5638 Given a piecewise cubic Hermite function - such as from
5639 L</pchip_chim> - evaluate the function (C<$fe>) at
5640 a set of points (C<$xe>).
5641 If derivative values are also required, use L</pchip_chfd>.
5642 EOF
5643 );
5644  
5645 pp_def('pchip_chia',
5646 Pars => 'x(n); f(n); d(n); la(); lb();
5647 [o]ans(); indx [o]ierr(); int [o]skip()',
5648 GenericTypes => $F,
5649 RedoDimsCode => <<'EOF',
5650 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
5651 EOF
5652 Code => pp_line_numbers(__LINE__, <<'EOF'),
5653 PDL_Indx ia, ib, il;
5654 $GENERIC() a = $la(), b = $lb(), xa, xb;
5655 PDL_Indx ir, n = $SIZE(n);
5656 $GENERIC() value = 0.;
5657 if (!$skip()) {
5658 loop (n=1) %{
5659 if ($x() > $x(n=>n-1)) continue;
5660 $ierr() = -1;
5661 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
5662 %}
5663 }
5664 /* FUNCTION DEFINITION IS OK, GO ON. */
5665 $skip() = 1;
5666 $ierr() = 0;
5667 if (a < $x(n=>0) || a > $x(n=>n-1)) {
5668 ++($ierr());
5669 }
5670 if (b < $x(n=>0) || b > $x(n=>n-1)) {
5671 $ierr() += 2;
5672 }
5673 /* COMPUTE INTEGRAL VALUE. */
5674 if (a != b) {
5675 xa = PDLMIN(a,b);
5676 xb = PDLMAX(a,b);
5677 if (xb <= $x(n=>1)) {
5678 /* INTERVAL IS TO LEFT OF X(2), SO USE FIRST CUBIC. */
5679 /* --------------------------------------- */
5680 $CHFIE($x(n=>0), $x(n=>1), $f(n=>0), $f(n=>1),
5681 $d(n=>0), $d(n=>1), a, b, value);
5682 /* --------------------------------------- */
5683 } else if (xa >= $x(n=>n-2)) {
5684 /* INTERVAL IS TO RIGHT OF X(N-1), SO USE LAST CUBIC. */
5685 /* ------------------------------------------ */
5686 $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);
5687 /* ------------------------------------------ */
5688 } else {
5689 /* 'NORMAL' CASE -- XA.LT.XB, XA.LT.X(N-1), XB.GT.X(2). */
5690 /* ......LOCATE IA AND IB SUCH THAT */
5691 /* X(IA-1).LT.XA.LE.X(IA).LE.X(IB).LE.XB.LE.X(IB+1) */
5692 ia = 0;
5693 loop (n=:-1) %{
5694 if (xa > $x())
5695 ia = n + 1;
5696 %}
5697 /* IA = 1 IMPLIES XA.LT.X(1) . OTHERWISE, */
5698 /* IA IS LARGEST INDEX SUCH THAT X(IA-1).LT.XA,. */
5699 ib = n - 1;
5700 loop (n=:ia:-1) %{
5701 if (xb < $x())
5702 ib = n - 1;
5703 %}
5704 /* IB = N IMPLIES XB.GT.X(N) . OTHERWISE, */
5705 /* IB IS SMALLEST INDEX SUCH THAT XB.LT.X(IB+1) . */
5706 /* ......COMPUTE THE INTEGRAL. */
5707 if (ib <= ia) {
5708 /* THIS MEANS IB = IA-1 AND */
5709 /* (A,B) IS A SUBSET OF (X(IB),X(IA)). */
5710 /* ------------------------------------------- */
5711 $CHFIE($x(n=>ib), $x(n=>ia), $f(n=>ib),
5712 $f(n=>ia), $d(n=>ib), $d(n=>ia), a, b, value);
5713 /* ------------------------------------------- */
5714 } else {
5715 /* FIRST COMPUTE INTEGRAL OVER (X(IA),X(IB)). */
5716 /* (Case (IB .EQ. IA) is taken care of by initialization */
5717 /* of VALUE to ZERO.) */
5718 if (ib > ia-1) {
5719 /* --------------------------------------------- */
5720 $PCHID(ia, ib, value);
5721 /* --------------------------------------------- */
5722 }
5723 /* THEN ADD ON INTEGRAL OVER (XA,X(IA)). */
5724 if (xa < $x(n=>ia)) {
5725 /* Computing MAX */
5726 il = PDLMAX(0,ia - 1);
5727 ir = il + 1;
5728 /* ------------------------------------- */
5729 $GENERIC() chfie_ans = 0;
5730 $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);
5731 value += chfie_ans;
5732 /* ------------------------------------- */
5733 }
5734 /* THEN ADD ON INTEGRAL OVER (X(IB),XB). */
5735 if (xb > $x(n=>ib)) {
5736 /* Computing MIN */
5737 ir = PDLMIN(ib + 1,n-1);
5738 il = ir - 1;
5739 /* ------------------------------------- */
5740 $GENERIC() chfie_ans = 0;
5741 $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);
5742 value += chfie_ans;
5743 /* ------------------------------------- */
5744 }
5745 /* FINALLY, ADJUST SIGN IF NECESSARY. */
5746 if (a > b) {
5747 value = -value;
5748 }
5749 }
5750 }
5751 }
5752 $ans() = value;
5753 EOF
5754 ParamDesc => {
5755 x => <<'EOF',
5756 array of independent variable values. The elements
5757 of X must be strictly increasing (error return if not):
5758  
5759 X(I-1) .LT. X(I), I = 2(1)N.
5760 EOF
5761 f => <<'EOF',
5762 array of function values. F(I) is the value corresponding to X(I).
5763 EOF
5764 d => <<'EOF',
5765 should contain the derivative values, computed by L</pchip_chim>.
5766 See L</pchip_chid> if the integration limits are data points.
5767 EOF
5768 skip => <<'EOF',
5769 Set to 1 to skip checks on the input data.
5770 This will save time in case these checks have already
5771 been performed (say, in L</pchip_chim> or L</pchip_chic>).
5772 Will be set to TRUE on return with IERR E<gt>= 0.
5773 EOF
5774 la => <<'EOF',
5775 The values of C<$la> and C<$lb> do not have
5776 to lie within C<$x>, although the resulting integral
5777 value will be highly suspect if they are not.
5778 EOF
5779 lb => <<'EOF',
5780 See la
5781 EOF
5782 ierr => <<'EOF',
5783 Error status:
5784  
5785 =over
5786  
5787 =item *
5788  
5789 0 if successful.
5790  
5791 =item *
5792  
5793 1 if C<$la> lies outside C<$x>.
5794  
5795 =item *
5796  
5797 2 if C<$lb> lies outside C<$x>.
5798  
5799 =item *
5800  
5801 3 if both 1 and 2 are true. (Note that this means that either [A,B]
5802 contains data interval or the intervals do not intersect at all.)
5803  
5804 =item *
5805  
5806 -1 if C<dim($x, 0) E<lt> 2>
5807  
5808 =item *
5809  
5810 -3 if C<$x> is not strictly increasing.
5811  
5812 =item *
5813  
5814 -4 if an error has occurred in a lower-level routine,
5815 which should never happen.
5816  
5817 =back
5818 EOF
5819 },
5820 Doc => <<'EOF',
5821 =for ref
5822  
5823 Integrate (x,f(x)) over arbitrary limits.
5824  
5825 Evaluate the definite integral of a piecewise
5826 cubic Hermite function over an arbitrary interval, given by C<[$la,$lb]>.
5827 EOF
5828 );
5829  
5830 pp_def('pchip_chid',
5831 Pars => 'x(n); f(n); d(n);
5832 indx ia(); indx ib();
5833 [o]ans(); indx [o]ierr(); int [o]skip()',
5834 RedoDimsCode => <<'EOF',
5835 if ($SIZE(n) < 2) $CROAK("NUMBER OF DATA POINTS LESS THAN TWO");
5836 EOF
5837 Code => <<'EOF',
5838 if (!$skip()) {
5839 loop (n=1) %{
5840 if ($x() > $x(n=>n-1)) continue;
5841 $ierr() = -1;
5842 $CROAK("X-ARRAY NOT STRICTLY INCREASING");
5843 %}
5844 }
5845 $PCHID($ia(), $ib(), $ans());
5846 EOF
5847 GenericTypes => $F,
5848 ParamDesc => {
5849 x => <<'EOF',
5850 array of independent variable values. The
5851 elements of X must be strictly increasing:
5852  
5853 X(I-1) .LT. X(I), I = 2(1)N.
5854  
5855 (Error return if not.)
5856  
5857 It is a fatal error to pass in data with C<N> E<lt> 2.
5858 EOF
5859 ia => <<'EOF',
5860 IA,IB -- (input) indices in X-array for the limits of integration.
5861 both must be in the range [0,N-1] (this is different from the Fortran
5862 version) - error return if not. No restrictions on their relative
5863 values.
5864 EOF
5865 ib => 'See ia for details',
5866 f => 'array of function values. F(I) is the value corresponding to X(I).',
5867 skip => <<'EOF',
5868 Set to 1 to skip checks on the input data.
5869 This will save time in case these checks have already
5870 been performed (say, in L</pchip_chim> or L</pchip_chic>).
5871 Will be set to TRUE on return with IERR of 0 or -4.
5872 EOF
5873 d => <<'EOF',
5874 should contain the derivative values, computed by L</pchip_chim>.
5875 EOF
5876 ierr => <<'EOF',
5877 Error status - this will be set, but an exception
5878 will also be thrown:
5879  
5880 =over
5881  
5882 =item *
5883  
5884 0 if successful.
5885  
5886 =item *
5887  
5888 -3 if C<$x> is not strictly increasing.
5889  
5890 =item *
5891  
5892 -4 if C<$ia> or C<$ib> is out of range.
5893  
5894 =back
5895  
5896 (VALUE will be zero in any of these cases.)
5897 NOTE: The above errors are checked in the order listed, and following
5898 arguments have B<NOT> been validated.
5899 EOF
5900 },
5901 Doc => <<'EOF',
5902 =for ref
5903  
5904 Evaluate the definite integral of a piecewise cubic Hermite function
5905 over an interval whose endpoints are data points.
5906  
5907 Evaluate the definite integral of a a piecewise cubic Hermite
5908 function between C<x($ia)> and C<x($ib)>.
5909  
5910 See L</pchip_chia> for integration between arbitrary
5911 limits.
5912 EOF
5913 );
5914  
5915 pp_def('pchip_chbs',
5916 Pars => 'x(n); f(n); d(n); sbyte knotyp();
5917 [o]t(nknots=CALC(2*$SIZE(n)+4));
5918 [o]bcoef(ndim=CALC(2*$SIZE(n))); indx [o]ierr()',
5919 GenericTypes => $F,
5920 Code => pp_line_numbers(__LINE__, <<'EOF'),
5921 /* Local variables */
5922 PDL_Indx n = $SIZE(n), ndim = $SIZE(ndim);
5923 $ierr() = 0;
5924 /* Check argument validity. Set up knot sequence if OK. */
5925 if ($knotyp() > 2) {
5926 $ierr() = -1;
5927 $CROAK("KNOTYP GREATER THAN 2");
5928 }
5929 if ($knotyp() >= 0) {
5930 /* Set up knot sequence. */
5931 do { /* inline dpchkt */
5932 /* Set interior knots. */
5933 PDL_Indx j = 0;
5934 loop (n) %{
5935 j += 2;
5936 $t(nknots=>j+1) = $t(nknots=>j) = $x();
5937 %}
5938 /* Assertion: At this point T(3),...,T(NDIM+2) have been set and */
5939 /* J=NDIM+1. */
5940 /* Set end knots according to KNOTYP. */
5941 $GENERIC() hbeg = $x(n=>1) - $x(n=>0);
5942 $GENERIC() hend = $x(n=>n-1) - $x(n=>n-2);
5943 if ($knotyp() == 1) {
5944 /* Extrapolate. */
5945 $t(nknots=>1) = $x(n=>0) - hbeg;
5946 $t(nknots=>ndim+2) = $x(n=>n-1) + hend;
5947 } else if ($knotyp() == 2) {
5948 /* Periodic. */
5949 $t(nknots=>1) = $x(n=>0) - hend;
5950 $t(nknots=>ndim+2) = $x(n=>n-1) + hbeg;
5951 } else {
5952 /* Quadruple end knots. */
5953 $t(nknots=>1) = $x(n=>0);
5954 $t(nknots=>ndim+2) = $x(n=>n-1);
5955 }
5956 $t(nknots=>0) = $t(nknots=>1);
5957 $t(nknots=>ndim+3) = $t(nknots=>ndim+2);
5958 } while (0); /* end inline dpchkt */
5959 }
5960 /* Compute B-spline coefficients. */
5961 $GENERIC() hnew = $t(nknots=>2) - $t(nknots=>0);
5962 loop (n) %{
5963 $GENERIC() hold = hnew;
5964 /* The following requires mixed mode arithmetic. */
5965 $GENERIC() dov3 = $d() / 3;
5966 $bcoef(ndim=>2*n) = $f() - hold * dov3;
5967 /* The following assumes T(2*K+1) = X(K). */
5968 hnew = $t(nknots=>2*n+4) - $t(nknots=>2*n+2);
5969 $bcoef(ndim=>2*n+1) = $f() + hnew * dov3;
5970 %}
5971 EOF
5972 ParamDesc => {
5973 f => <<'EOF',
5974 the array of dependent variable values.
5975 C<f(I)> is the value corresponding to C<x(I)>.
5976 EOF
5977 d => <<'EOF',
5978 the array of derivative values at the data points.
5979 C<d(I)> is the value corresponding to C<x(I)>.
5980 EOF
5981 knotyp => <<'EOF',
5982 flag which controls the knot sequence.
5983 The knot sequence C<t> is normally computed from C<$x>
5984 by putting a double knot at each C<x> and setting the end knot pairs
5985 according to the value of C<knotyp> (where C<m = ndim = 2*n>):
5986  
5987 =over
5988  
5989 =item *
5990  
5991 0 - Quadruple knots at the first and last points.
5992  
5993 =item *
5994  
5995 1 - Replicate lengths of extreme subintervals:
5996 C<t( 0 ) = t( 1 ) = x(0) - (x(1)-x(0))> and
5997 C<t(m+3) = t(m+2) = x(n-1) + (x(n-1)-x(n-2))>
5998  
5999 =item *
6000  
6001 2 - Periodic placement of boundary knots:
6002 C<t( 0 ) = t( 1 ) = x(0) - (x(n-1)-x(n-2))> and
6003 C<t(m+3) = t(m+2) = x(n) + (x(1)-x(0))>
6004  
6005 =item *
6006  
6007 E<lt>0 - Assume the C<nknots> and C<t> were set in a previous call.
6008 This option is provided for improved efficiency when used
6009 in a parametric setting.
6010  
6011 =back
6012 EOF
6013 t => <<'EOF',
6014 the array of C<2*n+4> knots for the B-representation
6015 and may be changed by the routine.
6016 If C<knotyp E<gt>= 0>, C<t> will be changed so that the
6017 interior double knots are equal to the x-values and the
6018 boundary knots set as indicated above,
6019 otherwise it is assumed that C<t> was set by a
6020 previous call (no check is made to verify that the data
6021 forms a legitimate knot sequence).
6022 EOF
6023 bcoef => 'the array of 2*N B-spline coefficients.',
6024 ierr => <<'EOF',
6025 Error status:
6026  
6027 =over
6028  
6029 =item *
6030  
6031 0 if successful.
6032  
6033 =item *
6034  
6035 -4 if C<knotyp E<gt> 2>. (recoverable)
6036  
6037 =item *
6038  
6039 -5 if C<knotyp E<lt> 0> and C<nknots != 2*n + 4>. (recoverable)
6040  
6041 =back
6042 EOF
6043 },
6044 Doc => <<'EOF',
6045 =for ref
6046  
6047 Piecewise Cubic Hermite function to B-Spline converter.
6048  
6049 Computes the B-spline representation of the PCH function
6050 determined by N,X,F,D. The output is the B-representation for the
6051 function: NKNOTS, T, BCOEF, NDIM, KORD.
6052  
6053 L</pchip_chic>, L</pchip_chim>, or L</pchip_chsp> can be used to
6054 determine an interpolating PCH function from a set of data. The
6055 B-spline routine L</pchip_bvalu> can be used to evaluate the
6056 resulting B-spline representation of the data
6057 (i.e. C<nknots>, C<t>, C<bcoeff>, C<ndim>, and
6058 C<kord>).
6059  
6060 Caution: Since it is assumed that the input PCH function has been
6061 computed by one of the other routines in the package PCHIP,
6062 input arguments N, X are B<not> checked for validity.
6063  
6064 Restrictions/assumptions:
6065  
6066 =over
6067  
6068 =item C<1>
6069  
6070 N.GE.2 . (not checked)
6071  
6072 =item C<2>
6073  
6074 X(i).LT.X(i+1), i=1,...,N . (not checked)
6075  
6076 =item C<4>
6077  
6078 KNOTYP.LE.2 . (error return if not)
6079  
6080 =item C<6>
6081  
6082 T(2*k+1) = T(2*k) = X(k), k=1,...,N . (not checked)
6083  
6084 * Indicates this applies only if KNOTYP.LT.0 .
6085  
6086 =back
6087  
6088 References: F. N. Fritsch, "Representations for parametric cubic
6089 splines," Computer Aided Geometric Design 6 (1989), pp.79-82.
6090 EOF
6091 );
6092  
6093 pp_def('pchip_bvalu',
6094 Pars => 't(nplusk); a(n); indx ideriv(); x();
6095 [o]ans(); indx [o] inbv();
6096 [t] work(k3=CALC(3*($SIZE(nplusk)-$SIZE(n))));',
6097 GenericTypes => $F,
6098 RedoDimsCode => <<'EOF',
6099 PDL_Indx k = $SIZE(nplusk) - $SIZE(n);
6100 if (k < 1) $CROAK("K DOES NOT SATISFY K.GE.1");
6101 if ($SIZE(n) < k) $CROAK("N DOES NOT SATISFY N.GE.K");
6102 EOF
6103 Code => pp_line_numbers(__LINE__, <<'EOF'),
6104 88 PDL_Indx k = $SIZE(nplusk) - $SIZE(n);
6105 88 ▶if ($ideriv() < 0 || $ideriv() >= k)
Branch: 6 branches
BranchTrueFalseTotal
if ($ideriv() < 0 || $ideriv() >= k) 197 5 202
if ($ideriv() < 0 || $ideriv() >= k) 36 202 238
if ($ideriv() < 0 || $ideriv() >= k) 20 202 222
if ($ideriv() < 0 || $ideriv() >= k) 3 217 220
if ($ideriv() < 0 || $ideriv() >= k) 2 197 199
if ($ideriv() < 0 || $ideriv() >= k) 0 0 0
6106 70 $CROAK("IDERIV DOES NOT SATISFY 0.LE.IDERIV.LT.K");
6107 PDL_Indx i;
6108 int mflag;
6109 /* *** FIND *I* IN (K,N) SUCH THAT T(I) .LE. X .LT. T(I+1) */
6110 /* (OR, .LE. T(I+1) IF T(I) .LT. T(I+1) = T(N+1)). */
6111 do { /* inlined dintrv */
6112 88 PDL_Indx ihi = $inbv() + 1, lxt = $SIZE(n);
6113 88 ▶ if (ihi >= lxt) {
Branch: 3 branches
BranchTrueFalseTotal
if (ihi >= lxt) { 0 0 0
if (ihi >= lxt) { 0 18 18
if (ihi >= lxt) { 0 0 0
6114 70 ▶ if ($x() >= $t(nplusk=>lxt)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() >= $t(nplusk=>lxt)) { 5 46 51
if ($x() >= $t(nplusk=>lxt)) { 12 34 46
if ($x() >= $t(nplusk=>lxt)) { 34 0 34
6115 70 mflag = 1; i = lxt; break;
6116 }
6117 70 ▶ if (lxt <= 0) {
Branch: 3 branches
BranchTrueFalseTotal
if (lxt <= 0) { 18 16 34
if (lxt <= 0) { 0 16 16
if (lxt <= 0) { 0 2 2
6118 70 mflag = -1; i = 0; break;
6119 }
6120 70 ihi = $inbv() = lxt;
6121 }
6122 88 char skipflag = 0;
6123 88 ▶ if ($x() < $t(nplusk=>ihi)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() < $t(nplusk=>ihi)) { 2 0 2
if ($x() < $t(nplusk=>ihi)) { 1 19 20
if ($x() < $t(nplusk=>ihi)) { 2 0 2
6124 70 PDL_Indx inbv = $inbv();
6125 70 ▶ if ($x() >= $t(nplusk=>inbv)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() >= $t(nplusk=>inbv)) { 0 19 19
if ($x() >= $t(nplusk=>inbv)) { 1 18 19
if ($x() >= $t(nplusk=>inbv)) { 0 18 18
6126 140 mflag = 0; i = $inbv(); break;
6127 }
6128 /* *** NOW X .LT. XT(IHI) . FIND LOWER BOUND */
6129 70 PDL_Indx istep = 1;
6130 70 while (1) {
6131 70 ihi = $inbv();
6132 202 $inbv() = ihi - istep;
6133 202 ▶ if ($inbv() <= 0) {
Branch: 3 branches
BranchTrueFalseTotal
if ($inbv() <= 0) { 18 0 18
if ($inbv() <= 0) { 7 11 18
if ($inbv() <= 0) { 11 0 11
6134 202 break;
6135 }
6136 202 PDL_Indx inbv = $inbv();
6137 36 ▶ if ($x() >= $t(nplusk=>inbv)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() >= $t(nplusk=>inbv)) { 1 17 18
if ($x() >= $t(nplusk=>inbv)) { 2 15 17
if ($x() >= $t(nplusk=>inbv)) { 2 13 15
6138 202 skipflag = 1;
6139 2 break;
6140 }
6141 202 istep <<= 1;
6142 }
6143 199 ▶ if (!skipflag) {
Branch: 3 branches
BranchTrueFalseTotal
if (!skipflag) { 0 13 13
if (!skipflag) { 0 13 13
if (!skipflag) { 0 29 29
6144 197 $inbv() = 0;
6145 197 ▶ if ($x() < $t(nplusk=>0)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() < $t(nplusk=>0)) { 25 4 29
if ($x() < $t(nplusk=>0)) { 0 27 27
if ($x() < $t(nplusk=>0)) { 1 26 27
6146 70 mflag = -1; i = 0; break;
6147 }
6148 }
6149 70 skipflag = 1;
6150 /* *** NOW X .GE. XT(ILO) . FIND UPPER BOUND */
6151 }
6152 18 ▶ if (!skipflag) {
Branch: 3 branches
BranchTrueFalseTotal
if (!skipflag) { 0 1 1
if (!skipflag) { 18 1 19
if (!skipflag) { 0 1 1
6153 18 PDL_Indx istep = 1;
6154 while (1) {
6155 138 $inbv() = ihi;
6156 68 ihi = $inbv() + istep;
6157 119 ▶ if (ihi >= lxt) break;
Branch: 3 branches
BranchTrueFalseTotal
if (ihi >= lxt) break; 0 1 1
if (ihi >= lxt) break; 8 262 270
if (ihi >= lxt) break; 75 123 198
6158 115 ▶ if ($x() < $t(nplusk=>ihi)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() < $t(nplusk=>ihi)) { 1 74 75
if ($x() < $t(nplusk=>ihi)) { 14 55 69
if ($x() < $t(nplusk=>ihi)) { 0 5 5
6159 130 skipflag = 1;
6160 48 break;
6161 }
6162 84 istep <<= 1;
6163 }
6164 52 ▶ if (!skipflag) {
Branch: 3 branches
BranchTrueFalseTotal
if (!skipflag) { 0 5 5
if (!skipflag) { 4 14 18
if (!skipflag) { 0 0 0
6165 38 ▶ if ($x() >= $t(nplusk=>lxt)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() >= $t(nplusk=>lxt)) { 0 5 5
if ($x() >= $t(nplusk=>lxt)) { 0 9 9
if ($x() >= $t(nplusk=>lxt)) { 1 4 5
6166 34 mflag = 1; i = lxt; break;
6167 }
6168 6 ihi = lxt;
6169 }
6170 }
6171 /* *** NOW XT(ILO) .LE. X .LT. XT(IHI) . NARROW THE INTERVAL */
6172 44 while (1) {
6173 62 PDL_Indx middle = ($inbv() + ihi) / 2;
6174 62 ▶ if (middle == $inbv()) {
Branch: 3 branches
BranchTrueFalseTotal
if (middle == $inbv()) { 6 5 11
if (middle == $inbv()) { 18 48 66
if (middle == $inbv()) { 0 6 6
6175 20 mflag = 0; i = $inbv(); break;
6176 }
6177 /* NOTE. IT IS ASSUMED THAT MIDDLE = ILO IN CASE IHI = ILO+1 */
6178 44 ▶ if ($x() < $t(nplusk=>middle))
Branch: 3 branches
BranchTrueFalseTotal
if ($x() < $t(nplusk=>middle)) 2 4 6
if ($x() < $t(nplusk=>middle)) 16 31 47
if ($x() < $t(nplusk=>middle)) 12 0 12
6179 14 ihi = middle;
6180 else
6181 32 $inbv() = middle;
6182 }
6183 } while (0); /* end dintrv inlined */
6184 20 ▶if ($x() < $t(nplusk=>k-1)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() < $t(nplusk=>k-1)) { 12 0 12
if ($x() < $t(nplusk=>k-1)) { 1 29 30
if ($x() < $t(nplusk=>k-1)) { 30 0 30
6185 2 $CROAK("X IS N0T GREATER THAN OR EQUAL TO T(K)");
6186 }
6187 20 ▶if (mflag != 0) {
Branch: 3 branches
BranchTrueFalseTotal
if (mflag != 0) { 30 0 30
if (mflag != 0) { 7 41 48
if (mflag != 0) { 13 10 23
6188 0 ▶ if ($x() > $t(nplusk=>i)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() > $t(nplusk=>i)) { 14 0 14
if ($x() > $t(nplusk=>i)) { 14 0 14
if ($x() > $t(nplusk=>i)) { 1 13 14
6189 2 $CROAK("X IS NOT LESS THAN OR EQUAL TO T(N+1)");
6190 }
6191 while (1) {
6192 72 ▶ if (i == k-1) {
Branch: 3 branches
BranchTrueFalseTotal
if (i == k-1) { 9 4 13
if (i == k-1) { 11 0 11
if (i == k-1) { 11 0 11
6193 2 $CROAK("A LEFT LIMITING VALUE CANNOT BE OBTAINED AT T(K)");
6194 }
6195 70 --i;
6196 2 ▶ if ($x() != $t(nplusk=>i)) {
Branch: 3 branches
BranchTrueFalseTotal
if ($x() != $t(nplusk=>i)) { 0 11 11
if ($x() != $t(nplusk=>i)) { 11 0 11
if ($x() != $t(nplusk=>i)) { 11 0 11
6197 19 break;
6198 }
6199 }
6200 /* *** DIFFERENCE THE COEFFICIENTS *IDERIV* TIMES */
6201 /* WORK(I) = AJ(I), WORK(K+I) = DP(I), WORK(K+K+I) = DM(I), I=1.K */
6202 }
6203 37 PDL_Indx imk = i+1 - k, j;
6204 109 ▶loop (k3=:k) %{
Branch: 3 branches
BranchTrueFalseTotal
loop (k3=:k) %{ 0 11 11
loop (k3=:k) %{ 75 26 101
loop (k3=:k) %{ 11 0 11
6205 90 $work() = $a(n=>imk+k3);
6206 %}
6207 36 ▶if ($ideriv() != 0) {
Branch: 3 branches
BranchTrueFalseTotal
if ($ideriv() != 0) { 11 0 11
if ($ideriv() != 0) { 0 29 29
if ($ideriv() != 0) { 5 6 11
6208 18 ▶ for (j = 0; j < $ideriv(); ++j) {
Branch: 3 branches
BranchTrueFalseTotal
for (j = 0; j < $ideriv(); ++j) { 0 12 12
for (j = 0; j < $ideriv(); ++j) { 1 23 24
for (j = 0; j < $ideriv(); ++j) { 2 1 3
6209 88 PDL_Indx kmj = k - j - 1;
6210 88 $GENERIC() fkmj = kmj;
6211 88 ▶ loop (k3=0:kmj) %{
Branch: 3 branches
BranchTrueFalseTotal
loop (k3=0:kmj) %{ 1 2 3
loop (k3=0:kmj) %{ 0 2 2
loop (k3=0:kmj) %{ 159 2 161
6212 88 PDL_Indx ihi = i+1 + k3;
6213 18 $work() = ($work(k3=>k3+1) - $work()) / ($t(nplusk=>ihi) - $t(nplusk=>ihi-kmj)) * fkmj;
6214 %}
6215 }
6216 /* *** COMPUTE VALUE AT *X* IN (T(I),T(I+1)) OF IDERIV-TH DERIVATIVE, */
6217 /* GIVEN ITS RELEVANT B-SPLINE COEFF. IN AJ(1),...,AJ(K-IDERIV). */
6218 }
6219 106 PDL_Indx km1 = k - 1;
6220 36 ▶if ($ideriv() != km1) {
Branch: 3 branches
BranchTrueFalseTotal
if ($ideriv() != km1) { 0 161 161
if ($ideriv() != km1) { 46 133 179
if ($ideriv() != km1) { 24 109 133
6221 18 PDL_Indx j, j1 = k, kpk = k + k, j2 = kpk, kmider = k - $ideriv();
6222 90 ▶ for (j = 0; j < kmider; ++j) {
Branch: 3 branches
BranchTrueFalseTotal
for (j = 0; j < kmider; ++j) { 25 84 109
for (j = 0; j < kmider; ++j) { 99 75 174
for (j = 0; j < kmider; ++j) { 29 28 57
6223 160 PDL_Indx ipj = i + j + 1;
6224 160 $work(k3=>j1) = $t(nplusk=>ipj) - $x();
6225 160 $work(k3=>j2) = $x() - $t(nplusk=>i-j);
6226 160 ++j1;
6227 160 ++j2;
6228 }
6229 159 ▶ for (j = $ideriv(); j < km1; ++j) {
Branch: 3 branches
BranchTrueFalseTotal
for (j = $ideriv(); j < km1; ++j) { 28 0 28
for (j = $ideriv(); j < km1; ++j) { 54 21 75
for (j = $ideriv(); j < km1; ++j) { 0 2 2
6230 139 PDL_Indx kmj = k - j - 1, ilo = kpk + kmj - 1;
6231 245 ▶ loop (k3=0:kmj) %{
Branch: 3 branches
BranchTrueFalseTotal
loop (k3=0:kmj) %{ 2 0 2
loop (k3=0:kmj) %{ 108 103 211
loop (k3=0:kmj) %{ 47 2 49
6232 121 $work() = ($work(k3=>k3+1) * $work(k3=>ilo) + $work() *
6233 108 $work(k3=>k+k3)) / ($work(k3=>ilo) + $work(k3=>k+k3));
6234 108 --ilo;
6235 %}
6236 }
6237 }
6238 18 $ans() = $work(k3=>0);
6239 EOF
6240 ParamDesc => {
6241 t => <<'EOF',
6242 knot vector of length N+K
6243 EOF
6244 a => <<'EOF',
6245 B-spline coefficient vector of length N,
6246 the number of B-spline coefficients; N = sum of knot multiplicities-K
6247 EOF
6248 ideriv => <<'EOF',
6249 order of the derivative, 0 .LE. IDERIV .LE. K-1
6250  
6251 IDERIV=0 returns the B-spline value
6252 EOF
6253 x => <<'EOF',
6254 T(K) .LE. X .LE. T(N+1)
6255 EOF
6256 inbv => <<'EOF',
6257 contains information for efficient processing after the initial
6258 call and INBV must not
6259 be changed by the user. Distinct splines require distinct INBV parameters.
6260 EOF
6261 ans => <<'EOF',
6262 value of the IDERIV-th derivative at X
6263 EOF
6264 },
6265 Doc => <<'EOF',
6266 =for ref
6267  
6268 Evaluate the B-representation of a B-spline at X for the
6269 function value or any of its derivatives.
6270  
6271 Evaluates the B-representation C<(T,A,N,K)> of a B-spline
6272 at C<X> for the function value on C<IDERIV = 0> or any of its
6273 derivatives on C<IDERIV = 1,2,...,K-1>. Right limiting values
6274 (right derivatives) are returned except at the right end
6275 point C<X=T(N+1)> where left limiting values are computed. The
6276 spline is defined on C<T(K) .LE. X .LE. T(N+1)>. BVALU returns
6277 a fatal error message when C<X> is outside of this interval.
6278  
6279 To compute left derivatives or left limiting values at a
6280 knot C<T(I)>, replace C<N> by C<I-1> and set C<X=T(I)>, C<I=K+1,N+1>.
6281  
6282 References: Carl de Boor, Package for calculating with B-splines,
6283 SIAM Journal on Numerical Analysis 14, 3 (June 1977), pp. 441-472.
6284 EOF
6285 );
6286  
6287 pp_addpm({At=>'Bot'},<<'EOD');
6288  
6289 =head1 AUTHOR
6290  
6291 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu). Contributions
6292 by Christian Soeller (c.soeller@auckland.ac.nz), Karl Glazebrook
6293 (kgb@aaoepp.aao.gov.au), Craig DeForest (deforest@boulder.swri.edu)
6294 and Jarle Brinchmann (jarle@astro.up.pt)
6295 All rights reserved. There is no warranty. You are allowed
6296 to redistribute this software / documentation under certain
6297 conditions. For details, see the file COPYING in the PDL
6298 distribution. If this file is separated from the PDL distribution,
6299 the copyright notice should be included in the file.
6300  
6301 Updated for CPAN viewing compatibility by David Mertens.
6302  
6303 =cut
6304  
6305 EOD
6306  
6307 pp_done();
« lib/PDL/Core/pdlaffine.c ↑ Summary lib/PDL/ImageND-pp-contour_segments.c »