1Core(3) User Contributed Perl Documentation Core(3)
2
6 PDL::Core - fundamental PDL functionality
7
9 Methods and functions for type conversions, PDL creation, type conver‐
10 sion, threading etc.
11
13 use PDL::Core; # Normal routines
14 use PDL::Core ':Internal'; # Hairy routines
15
17 pdl
18 piddle constructor - creates new piddle from perl scalars/arrays and
20 piddles
21 $a = pdl(SCALAR⎪ARRAY REFERENCE⎪ARRAY);
23 $a = pdl [1..10]; # 1D array
25 $a = pdl ([1..10]); # 1D array
26 $a = pdl (1,2,3,4); # Ditto
27 $b = pdl [[1,2,3],[4,5,6]]; # 2D 3x2 array
28 $b = pdl 42 # 0-dimensional scalar
29 $c = pdl $a; # Make a new copy
30 $a = pdl([1,2,3],[4,5,6]); # 2D
31 $a = pdl([[1,2,3],[4,5,6]]); # 2D
32 Note the last two are equivalent - a list is automatically converted to
34 a list reference for syntactic convenience. i.e. you can omit the outer
35 "[]"
36 You can mix and match arrays, array refs, and PDLs in your argument
38 list, and "pdl" will sort them out. You get back a PDL whose last
39 (slowest running) dim runs across the top level of the list you hand
40 in, and whose first (fastest running) dim runs across the deepest level
41 that you supply.
42 Throwing a PDL into the mix has the same effect as throwing in a list
44 ref:
45 pdl(pdl(1,2),[3,4])
47 is the same as
49 pdl([1,2],[3,4]).
51 All of the dimensions in the list are "padded-out" with undefval to
53 meet the widest dim in the list, so (e.g.)
54 $a = pdl([[1,2,3],[2]])
56 gives you the same answer as
58 $a = pdl([[1,2,3],[2,undef,undef]]);
60 "pdl()" is a functional synonym for the 'new' constructor, e.g.:
62 $x = new PDL [1..10];
64 In order to control how undefs are handled in converting from perl
66 lists to PDLs, one can set the variable $PDL::undefval. For example:
67 $foo = [[1,2,undef],[undef,3,4]];
69 $PDL::undefval = -999;
70 $f = pdl $foo;
71 print $f
72 [
73 [ 1 2 -999]
74 [-999 3 4]
75 ]
76 $PDL::undefval defaults to zero.
78 null
80 Returns a 'null' piddle.
82 $x = null;
84 "null()" has a special meaning to PDL::PP. It is used to flag a special
86 kind of empty piddle, which can grow to appropriate dimensions to store
87 a result (as opposed to storing a result in an existing piddle).
88 perldl> sumover sequence(10,10), $ans=null;p $ans
90 [45 145 245 345 445 545 645 745 845 945]
91 nullcreate
93 Returns a 'null' piddle.
95 $x = PDL->nullcreate($arg)
97 This is an routine used by many of the threading primitives (i.e.
99 sumover, minimum, etc.) to generate a null piddle for the function's
100 output that will behave properly for derived (or subclassed) PDL
101 objects.
102 For the above usage: If $arg is a PDL, or a derived PDL, then
104 "$arg->null" is returned. If $arg is a scalar (i.e. a zero-dimensional
105 PDL) then "$PDL->null" is returned.
106 PDL::Derived->nullcreate(10)
108 returns PDL::Derived->null.
109 PDL->nullcreate($pdlderived)
110 returns $pdlderived->null.
111 nelem
113 Return the number of elements in a piddle
115 $n = nelem($piddle); $n = $piddle->nelem;
117 $mean = sum($data)/nelem($data);
119 dims
121 Return piddle dimensions as a perl list
123 @dims = $piddle->dims; @dims = dims($piddle);
125 perldl> p @tmp = dims zeroes 10,3,22
127 10 3 22
128 ndims
130 Returns the number of dimensions in a piddle. Alias for getndims.
132 getndims
134 Returns the number of dimensions in a piddle
136 $ndims = $piddle->getndims;
138 perldl> p zeroes(10,3,22)->getndims
140 3
141 dim
143 Returns the size of the given dimension of a piddle. Alias for getdim.
145 getdim
147 Returns the size of the given dimension.
149 $dim0 = $piddle->getdim(0);
151 perldl> p zeroes(10,3,22)->getdim(1)
153 3
154 Negative indices count from the end of the dims array. Indices beyond
156 the end will return a size of 1. This reflects the idea that any pdl is
157 equivalent to an infinitely dimensional array in which only a finite
158 number of dimensions have a size different from one. For example, in
159 that sense a 3D piddle of shape [3,5,2] is equivalent to a
160 [3,5,2,1,1,1,1,1,....] piddle. Accordingly,
161 print $a->getdim(10000);
163 will print 1 for most practically encountered piddles.
165 topdl
167 alternate piddle constructor - ensures arg is a piddle
169 $a = topdl(SCALAR⎪ARRAY REFERENCE⎪ARRAY);
171 The difference between pdl() and "topdl()" is that the latter will just
173 'fall through' if the argument is already a piddle. It will return a
174 reference and NOT a new copy.
175 This is particulary useful if you are writing a function which is doing
177 some fiddling with internals and assumes a piddle argument (e.g. for
178 method calls). Using "topdl()" will ensure nothing breaks if passed
179 with '2'.
180 Note that "topdl()" is not exported by default (see example below for
182 usage).
183 use PDL::Core ':Internal'; # use the internal routines of
185 # the Core module
186 $a = topdl 43; # $a is piddle with value '43'
188 $b = topdl $piddle; # fall through
189 $a = topdl (1,2,3,4); # Convert 1D array
190 PDL::get_datatype
192 Internal: Return the numeric value identifying the piddle datatype
194 $x = $piddle->get_datatype;
196 Mainly used for internal routines.
198 NOTE: get_datatype returns 'just a number' not any special type object,
200 unlike type.
201 howbig
203 Returns the size of a piddle datatype in bytes.
205 Note that "howbig()" is not exported by default (see example below for
207 usage).
208 use PDL::Core ':Internal'; # use the internal routines of
210 # the Core module
211 $size = howbig($piddle->get_datatype);
213 Mainly used for internal routines.
215 NOTE: NOT a method! This is because get_datatype returns 'just a num‐
217 ber' not any special object.
218 perldl> p howbig(ushort([1..10])->get_datatype)
220 2
221 get_dataref
223 Return the internal data for a piddle, as a perl SCALAR ref.
225 Most piddles hold their internal data in a packed perl string, to take
227 advantage of perl's memory management. This gives you direct access to
228 the string, which is handy when you need to manipulate the binary data
229 directly (e.g. for file I/O). If you modify the string, you'll need to
230 call upd_data afterward, to make sure that the piddle points to the new
231 location of the underlying perl variable.
232 You shouldn't mess with the SV unless you've called make_physical or
234 something similar. You definitely don't want to do anything to the SV
235 to truncate or deallocate the string, unless you correspondingly call
236 reshape to make the PDL match its new data dimension.
237 You definitely don't want to use get_dataref unless you know what you
239 are doing (or are trying to find out): you can end up scrozzling memory
240 if you shrink or eliminate the string representation of the variable.
241 Here be dragons.
242 upd_data
244 Update the data pointer in a piddle to match its perl SV.
246 This is useful if you've been monkeying with the packed string repre‐
248 sentation of the PDL, which you probably shouldn't be doing anyway.
249 (see get_dataref.)
250 PDL::threadids
252 Returns the piddle thread IDs as a perl list
254 Note that "threadids()" is not exported by default (see example below
256 for usage).
257 use PDL::Core ':Internal'; # use the internal routines of
259 # the Core module
260 @ids = threadids $piddle;
262 doflow
264 Turn on/off dataflow
266 $x->doflow; doflow($x);
268 flows
270 Whether or not a piddle is indulging in dataflow
272 something if $x->flows; $hmm = flows($x);
274 PDL::new
276 new piddle constructor method
278 $x = PDL->new(SCALAR⎪ARRAY⎪ARRAY REF);
280 $x = PDL->new(42);
282 $y = new PDL [1..10];
283 Constructs piddle from perl numbers and lists.
285 copy
287 Make a physical copy of a piddle
289 $new = $old->copy;
291 Since "$new = $old" just makes a new reference, the "copy" method is
293 provided to allow real independent copies to be made.
294 PDL::hdr_copy
296 Return an explicit copy of the header of a PDL.
298 hdr_copy is just a wrapper for the internal routine _hdr_copy, which
300 takes the hash ref itself. That is the routine which is used to make
301 copies of the header during normal operations if the hdrcpy() flag of a
302 PDL is set.
303 General-purpose deep copies are expensive in perl, so some simple opti‐
305 mization happens:
306 If the header is a tied array or a blessed hash ref with an associated
308 method called "copy", then that ->copy method is called. Otherwise,
309 all elements of the hash are explicitly copied. References are recur‐
310 sively deep copied.
311 This routine seems to leak memory.
313 PDL::unwind
315 Return a piddle which is the same as the argument except that all
317 threadids have been removed.
318 $y = $x->unwind;
320 PDL::make_physical
322 Make sure the data portion of a piddle can be accessed from XS code.
324 $a->make_physical;
326 $a->call_my_xs_method;
327 Ensures that a piddle gets its own allocated copy of data. This obvi‐
329 ously implies that there are certain piddles which do not have their
330 own data. These are so called virtual piddles that make use of the
331 vaffine optimisation (see PDL::Indexing). They do not have their own
332 copy of data but instead store only access information to some (or all)
333 of another piddle's data.
334 Note: this function should not be used unless absolutely neccessary
336 since otherwise memory requirements might be severly increased. Instead
337 of writing your own XS code with the need to call "make_physical" you
338 might want to consider using the PDL preprocessor (see PDL::PP) which
339 can be used to transparently access virtual piddles without the need to
340 physicalise them (though there are exceptions).
341 dummy
343 Insert a 'dummy dimension' of given length (defaults to 1)
345 No relation to the 'Dungeon Dimensions' in Discworld!
347 Negative positions specify relative to last dimension, i.e. "dummy(-1)"
349 appends one dimension at end, "dummy(-2)" inserts a dummy dimension in
350 front of the last dim, etc.
351 If you specify a dimension position larger than the existing dimension
353 list of your PDL, the PDL gets automagically padded with extra dummy
354 dimensions so that you get the dim you asked for, in the slot you asked
355 for. This could cause you trouble if, for example, you ask for
356 $a->dummy(5000,1) because $a will get 5,000 dimensions, each of rank 1.
357 Because padding at the beginning of the dimension list moves existing
359 dimensions from slot to slot, it's considered unsafe, so automagic pad‐
360 ding doesn't work for large negative indices -- only for large positive
361 indices.
362 $y = $x->dummy($position[,$dimsize]);
364 perldl> p sequence(3)->dummy(0,3)
366 [
367 [0 0 0]
368 [1 1 1]
369 [2 2 2]
370 ]
371 perldl> p sequence(3)->dummy(3,2)
373 [
374 [
375 [0 1 2]
376 ]
377 [
378 [0 1 2]
379 ]
380 ]
381 perldl> p sequence(3)->dummy(-3,2)
383 For safety, <pos> < -(dims+1) is not allowed in dummy, allowed min=-2.
384 clump
386 "clumps" several dimensions into one large dimension
388 If called with one argument $n clumps the first $n dimensions into one.
390 For example, if $a has dimensions "(5,3,4)" then after
391 $b = $a->clump(2); # Clump 2 first dimensions
393 the variable $b will have dimensions "(15,4)" and the element
395 "$b->at(7,3)" refers to the element "$a->at(1,2,3)".
396 Use "clump(-1)" to flatten a piddle. The method flat is provided as a
398 convenient alias.
399 Clumping with a negative dimension in general leaves that many dimen‐
401 sions behind -- e.g. clump(-2) clumps all of the first few dimensions
402 into a single one, leaving a 2-D piddle.
403 If "clump" is called with an index list with more than one element it
405 is treated as a list of dimensions that should be clumped together into
406 one. The resulting clumped dim is placed at the position of the lowest
407 index in the list. This convention ensures that "clump" does the
408 expected thing in the usual cases. The following example demonstrates
409 typical usage:
410 $a = sequence 2,3,3,3,5; # 5D piddle
412 $c = $a->clump(1..3); # clump all the dims 1 to 3 into one
413 print $c->info; # resulting 3D piddle has clumped dim at pos 1
414 PDL: Double D [2,27,5]
415 thread_define
417 define functions that support threading at the perl level
419 thread_define 'tline(a(n);b(n))', over {
421 line $_[0], $_[1]; # make line compliant with threading
422 };
423 "thread_define" provides some support for threading (see PDL::Indexing)
425 at the perl level. It allows you to do things for which you normally
426 would have resorted to PDL::PP (see PDL::PP); however, it is most use‐
427 ful to wrap existing perl functions so that the new routine supports
428 PDL threading.
429 "thread_define" is used to define new threading aware functions. Its
431 first argument is a symbolic repesentation of the new function to be
432 defined. The string is composed of the name of the new function fol‐
433 lowed by its signature (see PDL::Indexing and PDL::PP) in parentheses.
434 The second argument is a subroutine that will be called with the slices
435 of the actual runtime arguments as specified by its signature. Correct
436 dimension sizes and minimal number of dimensions for all arguments will
437 be checked (assuming the rules of PDL threading, see PDL::Indexing).
438 The actual work is done by the "signature" class which parses the sig‐
440 nature string, does runtime dimension checks and the routine "thread‐
441 over" that generates the loop over all appropriate slices of pdl argu‐
442 ments and creates pdls as needed.
443 Similar to "pp_def" and its "OtherPars" option it is possible to define
445 the new function so that it accepts normal perl args as well as pid‐
446 dles. You do this by using the "NOtherPars" parameter in the signature.
447 The number of "NOtherPars" specified will be passed unaltered into the
448 subroutine given as the second argument of "thread_define". Let's
449 illustrate this with an example:
450 PDL::thread_define 'triangles(inda();indb();indc()), NOtherPars => 2',
452 PDL::over {
453 ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
454 };
455 This defines a function "triangles" that takes 3 piddles as input plus
457 2 arguments which are passed into the routine unaltered. This routine
458 is used to collect lists of indices into a perl scalar that is passed
459 by reference. Each line is preceded by a prefix passed as $_[4]. Here
460 is typical usage:
461 $txt = '';
463 triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
464 print $txt;
465 resulting in the following output
467 1,1,0,-1,
469 2,1,0,-1,
470 3,1,0,-1,
471 which is used in PDL::Graphics::TriD::VRML to generate VRML output.
473 Currently, this is probably not much more than a POP (proof of princi‐
475 ple) but is hoped to be useful enough for some real life work.
476 Check PDL::PP for the format of the signature. Currently, the "[t]"
478 qualifier and all type qualifiers are ignored.
479 PDL::thread
481 Use explicit threading over specified dimensions (see also PDL::Index‐
483 ing)
484 $b = $a->thread($dim,[$dim1,...])
486 $a = zeroes 3,4,5;
488 $b = $a->thread(2,0);
489 Same as PDL::thread1, i.e. uses thread id 1.
491 diagonal
493 Returns the multidimensional diagonal over the specified dimensions.
495 $d = $x->diagonal(dim1, dim2,...)
497 perldl> $a = zeroes(3,3,3);
499 perldl> ($b = $a->diagonal(0,1))++;
500 perldl> p $a
501 [
502 [
503 [1 0 0]
504 [0 1 0]
505 [0 0 1]
506 ]
507 [
508 [1 0 0]
509 [0 1 0]
510 [0 0 1]
511 ]
512 [
513 [1 0 0]
514 [0 1 0]
515 [0 0 1]
516 ]
517 ]
518 PDL::thread1
520 Explicit threading over specified dims using thread id 1.
522 $xx = $x->thread1(3,1)
524 Wibble
526 Convenience function interfacing to PDL::Slices::threadI.
528 PDL::thread2
530 Explicit threading over specified dims using thread id 2.
532 $xx = $x->thread2(3,1)
534 Wibble
536 Convenience function interfacing to PDL::Slices::threadI.
538 PDL::thread3
540 Explicit threading over specified dims using thread id 3.
542 $xx = $x->thread3(3,1)
544 Wibble
546 Convenience function interfacing to PDL::Slices::threadI.
548 sever
550 sever any links of this piddle to parent piddles
552 In PDL it is possible for a piddle to be just another view into another
554 piddle's data. In that case we call this piddle a virtual piddle and
555 the original piddle owning the data its parent. In other languages
556 these alternate views sometimes run by names such as alias or smart
557 reference.
558 Typical functions that return such piddles are "slice", "xchg",
560 "index", etc. Sometimes, however, you would like to separate the vir‐
561 tual piddle from its parent's data and just give it a life of its own
562 (so that manipulation of its data doesn't change the parent). This is
563 simply achieved by using "sever". For example,
564 $a = $pdl->index(pdl(0,3,7))->sever;
566 $a++; # important: $pdl is not modified!
567 In many (but not all) circumstances it acts therefore similar to copy.
569 However, in general performance is better with "sever" and secondly,
570 "sever" doesn't lead to futile copying when used on piddles that
571 already have their own data. On the other hand, if you really want to
572 make sure to work on a copy of a piddle use copy.
573 $a = zeroes(20);
575 $a->sever; # NOOP since $a is already its own boss!
576 Again note: "sever" is not the same as copy! For example,
578 $a = zeroes(1); # $a does not have a parent, i.e. it is not a slice etc
580 $b = $a->sever; # $b is now pointing to the same piddle as $a
581 $b++;
582 print $a;
583 [1]
584 but
586 $a = zeroes(1);
588 $b = $a->copy; # $b is now pointing to a new piddle
589 $b++;
590 print $a;
591 [0]
592 PDL::info
594 Return formatted information about a piddle.
596 $x->info($format_string);
598 print $x->info("Type: %T Dim: %-15D State: %S");
600 Returns a string with info about a piddle. Takes an optional argument
602 to specify the format of information a la sprintf. Format specifiers
603 are in the form "%<width><letter>" where the width is optional and the
604 letter is one of
605 T Type
607 D Formatted Dimensions
609 F Dataflow status
611 S Some internal flags (P=physical,V=Vaffine,C=changed)
613 C Class of this piddle, i.e. "ref $pdl"
615 A Address of the piddle struct as a unique identifier
617 M Calculated memory consumption of this piddle's data area
619 approx
621 test for approximately equal values (relaxed "==")
623 # ok if all corresponding values in
625 # piddles are within 1e-8 of each other
626 print "ok\n" if all approx $a, $b, 1e-8;
627 "approx" is a relaxed form of the "==" operator and often more appro‐
629 priate for floating point types ("float" and "double").
630 Usage:
632 $res = approx $a, $b [, $eps]
634 The optional parameter $eps is remembered across invocations and ini‐
636 tially set to 1e-6, e.g.
637 approx $a, $b; # last $eps used (1e-6 initially)
639 approx $a, $b, 1e-10; # 1e-10
640 approx $a, $b; # also 1e-10
641 mslice
643 Convenience interface to slice, allowing easier inclusion of dimensions
645 in perl code.
646 $a = $x->mslice(...);
648 # below is the same as $x->slice("5:7,:,3:4:2")
650 $a = $x->mslice([5,7],X,[3,4,2]);
651 nslice
653 Internally used interface to slice and dice that is the runtime part of
655 the PDL::NiceSlice implementation.
656 $a = $x->nslice(...);
658 # below is the same as $x->slice("5:7,:,3:4:2")
660 $a = $x->nslice([5,7],X,[3,4,2]);
661 It implements a superset of mslice's features. Should probably not be
663 used in your scripts. Rather resort to the PDL::NiceSlice interface.
664 inplace
666 Flag a piddle so that the next operation is done 'in place'
668 somefunc($x->inplace); somefunc(inplace $x);
670 In most cases one likes to use the syntax "$y = f($x)", however in many
672 case the operation "f()" can be done correctly 'in place', i.e. without
673 making a new copy of the data for output. To make it easy to use this,
674 we write "f()" in such a way that it operates in-place, and use
675 "inplace" to hint that a new copy should be disabled. This also makes
676 for clear syntax.
677 Obviously this will not work for all functions, and if in doubt see the
679 function's documentation. However one can assume this is true for all
680 elemental functions (i.e. those which just operate array element by
681 array element like "log10").
682 perldl> $x = xvals zeroes 10;
684 perldl> log10(inplace $x)
685 perldl> p $x
686 [ -Inf 0 0.30103 0.47712125 0.60205999 0.69897
687 0.77815125 0.84509804 0.90308999 0.95424251]
688 is_inplace
690 Test the in-place flag on a piddle
692 $out = ($in->is_inplace) ? $in : zeroes($in);
694 $in->set_inplace(0)
695 Provides access to the inplace hint flag, within the perl millieu.
697 That way functions you write can be inplace aware... If given an argu‐
698 ment the inplace flag will be set or unset depending on the value at
699 the same time. Can be used for shortcut tests that delete the inplace
700 flag while testing:
701 $out = ($in->is_inplace(0)) ? $in : zeroes($in); # test & unset!
703 set_inplace
705 Set the in-place flag on a piddle
707 $out = ($in->is_inplace) ? $in : zeroes($in);
709 $in->set_inplace(0);
710 Provides access to the inplace hint flag, within the perl millieu.
712 Useful mainly for turning it OFF, as inplace turns it ON more conve‐
713 niently.
714 new_or_inplace
716 Return back either the argument pdl or a copy of it depending on
718 whether it be flagged in-place or no. Handy for building inplace-aware
719 functions.
720 PDL::new_from_specification
722 Internal method: create piddle by specification
724 This is the argument processing method called by zeroes and some other
726 functions which constructs piddles from argument lists of the form:
727 [type], $nx, $ny, $nz,...
729 For $nx, $ny, etc. 0 and 1D piddles are allowed. Giving those has the
731 same effect as if saying "$arg->list", e.g.
732 1, pdl(5,2), 4
734 is equivalent to
736 1, 5, 2, 4
738 Note, however, that in all functions using "new_from_specification"
740 calling "func $piddle" will probably not do what you want. So to play
741 safe use (e.g. with zeroes)
742 $pdl = zeroes $dimpdl->list;
744 Calling
746 $pdl = zeroes $dimpdl;
748 will rather be equivalent to
750 $pdl = zeroes $dimpdl->dims;
752 However,
754 $pdl = zeroes ushort, $dimpdl;
756 will again do what you intended since it is interpreted as if you had
758 said
759 $pdl = zeroes ushort, $dimpdl->list;
761 This is unfortunate and confusing but no good solution seems obvious
763 that would not break existing scripts.
764 isempty
766 Test whether a piddle is empty
768 print "The piddle has zero dimension\n" if $pdl->isempty;
770 This function returns 1 if the piddle has zero elements. This is useful
772 in particular when using the indexing function which. In the case of no
773 match to a specified criterion, the returned piddle has zero dimension.
774 perldl> $a=sequence(10)
776 perldl> $i=which($a < -1)
777 perldl> print "I found no matches!\n" if ($a->isempty);
778 Note that having zero elements is rather different from the concept of
780 being a null piddle, see the PDL::FAQ and PDL::Indexing manpages for
781 discussions of this.
782 zeroes
784 construct a zero filled piddle from dimension list or template piddle.
786 Various forms of usage,
788 (i) by specification or (ii) by template piddle:
790 # usage type (i):
792 $a = zeroes([type], $nx, $ny, $nz,...);
793 $a = PDL->zeroes([type], $nx, $ny, $nz,...);
794 $a = $pdl->zeroes([type], $nx, $ny, $nz,...);
795 # usage type (ii):
796 $a = zeroes $b;
797 $a = $b->zeroes
798 zeroes inplace $a; # Equivalent to $a .= 0;
799 $a->inplace->zeroes; # ""
800 perldl> $z = zeroes 4,3
802 perldl> p $z
803 [
804 [0 0 0 0]
805 [0 0 0 0]
806 [0 0 0 0]
807 ]
808 perldl> $z = zeroes ushort, 3,2 # Create ushort array
809 [ushort() etc. with no arg returns a PDL::Types token]
810 See also new_from_specification for details on using piddles in the
812 dimensions list.
813 ones
815 construct a one filled piddle
817 $a = ones([type], $nx, $ny, $nz,...);
819 etc. (see 'zeroes')
820 see zeroes() and add one
822 See also new_from_specification for details on using piddles in the
824 dimensions list.
825 reshape
827 Change the shape (i.e. dimensions) of a piddle, preserving contents.
829 $x->reshape(NEWDIMS); reshape($x, NEWDIMS);
831 The data elements are preserved, obviously they will wrap differently
833 and get truncated if the new array is shorter. If the new array is
834 longer it will be zero-padded.
835 ***Potential incompatibility with earlier versions of PDL**** If the
837 list of "NEWDIMS" is empty "reshape" will just drop all dimensions of
838 size 1 (preserving the number of elements):
839 $a = sequence(3,4,5);
841 $b = $a(1,3);
842 $b->reshape();
843 print $b->info;
844 PDL: Double D [5]
845 Dimensions of size 1 will also be dropped if "reshape" is invoked with
847 the argument -1:
848 $b = $a->reshape(-1);
850 As opposed to "reshape" without arguments, "reshape(-1)" preserves
852 dataflow:
853 $a = ones(2,1,2);
855 $b = $a(0)->reshape(-1);
856 $b++;
857 print $a;
858 [
859 [
860 [2 1]
861 ]
862 [
863 [2 1]
864 ]
865 ]
866 Note: an explicit copy of slices is generally forced - this is the only
868 way (for now) of stopping a crash if $x is a slice. Important: Physi‐
869 cal piddles are changed inplace!
870 perldl> $x = sequence(10)
872 perldl> reshape $x,3,4; p $x
873 [
874 [0 1 2]
875 [3 4 5]
876 [6 7 8]
877 [9 0 0]
878 ]
879 perldl> reshape $x,5; p $x
880 [0 1 2 3 4]
881 squeeze
883 eliminate all singleton dimensions (dims of size 1)
885 $b = $a(0,0)->squeeze;
887 Alias for "reshape(-1)". Removes all singleton dimensions and preserves
889 dataflow. A more concise interface is provided by PDL::NiceSlice via
890 modifiers:
891 use PDL::NiceSlice;
893 $b = $a(0,0;-); # same as $a(0,0)->squeeze
894 flat
896 flatten a piddle (alias for "$pdl-"clump(-1)>)
898 $srt = $pdl->flat->qsort;
900 Useful method to make a 1D piddle from an arbitrarily sized input pid‐
902 dle. Data flows back and forth as usual with slicing routines. Falls
903 through if argument already <= 1D.
904 convert
906 Generic datatype conversion function
908 $y = convert($x, $newtype);
910 $y = convert $x, long
912 $y = convert $x, ushort
913 $newtype is a type number, for convenience they are returned by
915 "long()" etc when called without arguments.
916 Datatype_conversions
918 byte⎪short⎪ushort⎪long⎪longlong⎪float⎪double convert shorthands
920 $y = double $x; $y = ushort [1..10];
922 # all of byte⎪short⎪ushort⎪long⎪float⎪double behave similarly
923 When called with a piddle argument, they convert to the specific
925 datatype.
926 When called with a numeric or list / listref argument they construct a
928 new piddle. This is a convenience to avoid having to be long-winded and
929 say "$x = long(pdl(42))"
930 Thus one can say:
932 $a = float(1,2,3,4); # 1D
934 $a = float([1,2,3],[4,5,6]); # 2D
935 $a = float([[1,2,3],[4,5,6]]); # 2D
936 Note the last two are equivalent - a list is automatically converted to
938 a list reference for syntactic convenience. i.e. you can omit the outer
939 "[]"
940 When called with no arguments return a special type token. This allows
942 syntactical sugar like:
943 $x = ones byte, 1000,1000;
945 This example creates a large piddle directly as byte datatype in order
947 to save memory.
948 In order to control how undefs are handled in converting from perl
950 lists to PDLs, one can set the variable $PDL::undefval; see the func‐
951 tion pdl() for more details.
952 perldl> p $x=sqrt float [1..10]
954 [1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228]
955 perldl> p byte $x
956 [1 1 1 2 2 2 2 2 3 3]
957 byte
959 Convert to byte datatype - see 'Datatype_conversions'
961 short
963 Convert to short datatype - see 'Datatype_conversions'
965 ushort
967 Convert to ushort datatype - see 'Datatype_conversions'
969 long
971 Convert to long datatype - see 'Datatype_conversions'
973 longlong
975 Convert to longlong datatype - see 'Datatype_conversions'
977 float
979 Convert to float datatype - see 'Datatype_conversions'
981 double
983 Convert to double datatype - see 'Datatype_conversions'
985 type
987 return the type of a piddle as a blessed type object
989 A convenience function for use with the piddle constructors, e.g.
991 $b = PDL->zeroes($a->type,$a->dims,3);
993 die "must be float" unless $a->type == float;
994 See also the discussion of the "PDL::Type" class in PDL::Types. Note
996 that the "PDL::Type" objects have overloaded comparison and stringify
997 operators so that you can compare and print types:
998 $a = $a->float if $a->type < float;
1000 $t = $a->type; print "Type is $t\";
1001 list
1003 Convert piddle to perl list
1005 @tmp = list $x;
1007 Obviously this is grossly inefficient for the large datasets PDL is
1009 designed to handle. This was provided as a get out while PDL matured.
1010 It should now be mostly superseded by superior constructs, such as
1011 PP/threading. However it is still occasionally useful and is provied
1012 for backwards compatibility.
1013 for (list $x) {
1015 # Do something on each value...
1016 }
1017 listindices
1019 Convert piddle indices to perl list
1021 @tmp = listindices $x;
1023 @tmp now contains the values "0..nelem($x)".
1025 Obviously this is grossly inefficient for the large datasets PDL is
1027 designed to handle. This was provided as a get out while PDL matured.
1028 It should now be mostly superseded by superior constructs, such as
1029 PP/threading. However it is still occasionally useful and is provied
1030 for backwards compatibility.
1031 for $i (listindices $x) {
1033 # Do something on each value...
1034 }
1035 set
1037 Set a single value inside a piddle
1039 set $piddle, @position, $value
1041 @position is a coordinate list, of size equal to the number of dimen‐
1043 sions in the piddle. Occasionally useful, mainly provided for backwards
1044 compatibility as superseded by use of slice and assigment operator
1045 ".=".
1046 perldl> $x = sequence 3,4
1048 perldl> set $x, 2,1,99
1049 perldl> p $x
1050 [
1051 [ 0 1 2]
1052 [ 3 4 99]
1053 [ 6 7 8]
1054 [ 9 10 11]
1055 ]
1056 at
1058 Returns a single value inside a piddle as perl scalar.
1060 $z = at($piddle, @position); $z=$piddle->at(@position);
1062 @position is a coordinate list, of size equal to the number of dimen‐
1064 sions in the piddle. Occasionally useful in a general context, quite
1065 useful too inside PDL internals.
1066 perldl> $x = sequence 3,4
1068 perldl> p $x->at(1,2)
1069 7
1070 sclr
1072 return a single value from a piddle as a scalar
1074 $val = $a(10)->sclr;
1076 $val = sclr inner($a,$b);
1077 The "sclr" method is useful to turn a piddle into a normal Perl scalar.
1079 Its main advantage over using "at" for this purpose is the fact that
1080 you do not need to worry if the piddle is 0D, 1D or higher dimensional.
1081 Using "at" you have to supply the correct number of zeroes, e.g.
1082 $a = sequence(10);
1084 $b = $a->slice('4');
1085 print $b->sclr; # no problem
1086 print $b->at(); # error: needs at least one zero
1087 "sclr" is generally used when a Perl scalar is required instead of a
1089 one-element piddle. If the input is a multielement piddle the first
1090 value is returned as a Perl scalar. You can optionally switch on checks
1091 to ensure that the input piddle has only one element:
1092 PDL->sclr({Check => 'warn'}); # carp if called with multi-el pdls
1094 PDL->sclr({Check => 'barf'}); # croak if called with multi-el pdls
1095 are the commands to switch on warnings or raise an error if a multiele‐
1097 ment piddle is passed as input. Note that these options can only be set
1098 when "sclr" is called as a class method (see example above). Use
1099 PDL->sclr({Check=>0});
1101 to switch these checks off again (default setting); When called as a
1103 class method the resulting check mode is returned (0: no checking, 1:
1104 warn, 2: barf).
1105 cat
1107 concatentate piddles to N+1 dimensional piddle
1109 Takes a list of N piddles of same shape as argument, returns a single
1111 piddle of dimension N+1
1112 perldl> $x = cat ones(3,3),zeroes(3,3),rvals(3,3); p $x
1114 [
1115 [
1116 [1 1 1]
1117 [1 1 1]
1118 [1 1 1]
1119 ]
1120 [
1121 [0 0 0]
1122 [0 0 0]
1123 [0 0 0]
1124 ]
1125 [
1126 [1 1 1]
1127 [1 0 1]
1128 [1 1 1]
1129 ]
1130 ]
1131 dog
1133 Opposite of 'cat' :). Split N dim piddle to list of N-1 dim piddles
1135 Takes a single N-dimensional piddle and splits it into a list of N-1
1137 dimensional piddles. The breakup is done along the last dimension.
1138 Note the dataflown connection is still preserved by default, e.g.:
1139 perldl> $p = ones 3,3,3
1141 perldl> ($a,$b,$c) = dog $p
1142 perldl> $b++; p $p
1143 [
1144 [
1145 [1 1 1]
1146 [1 1 1]
1147 [1 1 1]
1148 ]
1149 [
1150 [2 2 2]
1151 [2 2 2]
1152 [2 2 2]
1153 ]
1154 [
1155 [1 1 1]
1156 [1 1 1]
1157 [1 1 1]
1158 ]
1159 ]
1160 Break => 1 Break dataflow connection (new copy)
1162 barf
1164 Standard error reporting routine for PDL.
1166 "barf()" is the routine PDL modules should call to report errors. This
1168 is because "barf()" will report the error as coming from the correct
1169 line in the module user's script rather than in the PDL module.
1170 It does this magic by unwinding the stack frames until it reaches a
1172 package NOT beginning with "PDL::". If you DO want it to report errors
1173 in some module PDL::Foo (e.g. when debugging PDL::Foo) then set the
1174 variable "$PDL::Foo::Debugging=1".
1175 Additionally if you set the variable "$PDL::Debugging=1" you will get a
1177 COMPLETE stack trace back up to the top level package.
1178 Finally "barf()" will try and report usage information from the PDL
1180 documentation database if the error message is of the form 'Usage:
1181 func'.
1182 Remember "barf()" is your friend. *Use* it!
1184 At the perl level:
1186 barf("User has too low an IQ!");
1188 In C or XS code:
1190 barf("You have made %d errors", count);
1192 Note: this is one of the few functions ALWAYS exported by PDL::Core
1194 gethdr
1196 Retrieve header information from a piddle
1198 $pdl=rfits('file.fits');
1200 $h=$pdl->gethdr;
1201 print "Number of pixels in the X-direction=$$h{NAXIS1}\n";
1202 The "gethdr" function retrieves whatever header information is con‐
1204 tained within a piddle. The header can be set with sethdr and is always
1205 a hash reference or undef.
1206 "gethdr" returns undef if the piddle has not yet had a header defined;
1208 compare with "hdr" and "fhdr", which are guaranteed to return a defined
1209 value.
1210 Note that gethdr() works by reference: you can modify the header in-
1212 place once it has been retrieved:
1213 $a = rfits($filename);
1215 $ah = $a->gethdr();
1216 $ah->{FILENAME} = $filename;
1217 It is also important to realise that in most cases the header is not
1219 automatically copied when you copy the piddle. See hdrcpy to enable
1220 automatic header copying.
1221 Here's another example: a wrapper around rcols that allows your piddle
1223 to remember the file it was read from and the columns could be easily
1224 written (here assuming that no regexp is needed, extensions are left as
1225 an exercise for the reader)
1226 sub ext_rcols {
1228 my ($file, @columns)=@_;
1229 my $header={};
1230 $$header{File}=$file;
1231 $$header{Columns}=\@columns;
1232 @piddles=rcols $file, @columns;
1234 foreach (@piddles) { $_->sethdr($header); }
1235 return @piddles;
1236 }
1237 hdr
1239 Retrieve or set header information from a piddle
1241 $pdl->hdr->{CDELT1} = 1;
1243 The "hdr" function allows convenient access to the header of a piddle.
1245 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1246 use it in a hash dereference as in the example. If the header does not
1247 yet exist, it gets autogenerated as an empty hash.
1248 Note that this is usually -- but not always -- What You Want. If you
1250 want to use a tied Astro::FITS::Header hash, for example, you should
1251 either construct it yourself and use "sethdr" to put it into the pid‐
1252 dle, or use fhdr instead. (Note that you should be able to write out
1253 the FITS file successfully regardless of whether your PDL has a tied
1254 FITS header object or a vanilla hash).
1255 fhdr
1257 Retrieve or set FITS header information from a piddle
1259 $pdl->fhdr->{CDELT1} = 1;
1261 The "fhdr" function allows convenient access to the header of a piddle.
1263 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1264 use it in a hash dereference as in the example. If the header does not
1265 yet exist, it gets autogenerated as a tied Astro::FITS::Header hash.
1266 Astro::FITS::Header tied hashes are better at matching the behavior of
1268 FITS headers than are regular hashes. In particular, the hash keys are
1269 CAsE INsEnSItiVE, unlike normal hash keys. See Astro::FITS::Header for
1270 details.
1271 If you do not have Astro::FITS::Header installed, you get back a normal
1273 hash instead of a tied object.
1274 sethdr
1276 Set header information of a piddle
1278 $pdl = zeroes(100,100);
1280 $h = {NAXIS=>2, NAXIS1=>100, NAXIS=>100, COMMENT=>"Sample FITS-style header"};
1281 # add a FILENAME field to the header
1282 $$h{FILENAME} = 'file.fits';
1283 $pdl->sethdr( $h );
1284 The "sethdr" function sets the header information for a piddle. You
1286 must feed in a hash ref or undef, and the header field of the PDL is
1287 set to be a new ref to the same hash (or undefined).
1288 The hash ref requirement is a speed bump put in place since the normal
1290 use of headers is to store fits header information and the like. Of
1291 course, if you want you can hang whatever ugly old data structure you
1292 want off of the header, but that makes life more complex.
1293 Remember that the hash is not copied -- the header is made into a ref
1295 that points to the same underlying data. To get a real copy without
1296 making any assumptions about the underlying data structure, you can use
1297 one of the following:
1298 use PDL::IO::Dumper;
1300 $pdl->sethdr( deep_copy($h) );
1301 (which is slow but general), or
1303 $pdl->sethdr( PDL::_hdr_copy($h) )
1305 (which uses the built-in sleazy deep copier), or (if you know that all
1307 the elements happen to be scalars):
1308 { my %a = %$h;
1310 $pdl->sethdr(\%a);
1311 }
1312 which is considerably faster but just copies the top level.
1314 The "sethdr" function must be given a hash reference or undef. For
1316 further information on the header, see gethdr, hdr, fhdr and hdrcpy.
1317 hdrcpy
1319 switch on/off/examine automatic header copying
1321 print "hdrs will be copied" if $a->hdrcpy;
1323 $a->hdrcpy(1); # switch on automatic header copying
1324 $b = $a->sumover; # and $b will inherit $a's hdr
1325 $a->hdrcpy(0); # and now make $a non-infectious again
1326 "hdrcpy" without an argument just returns the current setting of the
1328 flag. See also "hcpy" which returns its PDL argument (and so is useful
1329 in method-call pipelines).
1330 Normally, the optional header of a piddle is not copied automatically
1332 in pdl operations. Switching on the hdrcpy flag using the "hdrcpy"
1333 method will enable automatic hdr copying. Note that an actual deep copy
1334 gets made, which is rather processor-inefficient -- so avoid using
1335 header copying in tight loops!
1336 Most PDLs have the "hdrcpy" flag cleared by default; however, some rou‐
1338 tines (notably rfits) set it by default where that makes more sense.
1339 The "hdrcpy" flag is viral: if you set it for a PDL, then derived PDLs
1341 will get copies of the header and will also have their "hdrcpy" flags
1342 set. For example:
1343 $a = xvals(50,50);
1345 $a->hdrcpy(1);
1346 $a->hdr->{FOO} = "bar";
1347 $b = $a++;
1348 $c = $b++;
1349 print $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1350 $b->hdr->{FOO} = "baz";
1351 print $a->hdr->{FOO}, " - ", $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1352 will print:
1354 bar - bar
1356 bar - baz - bar
1357 hcpy
1359 Switch on/off automatic header copying, with PDL pass-through
1361 $a = rfits('foo.fits')->hcpy(0);
1363 $a = rfits('foo.fits')->hcpy(1);
1364 "hcpy" sets or clears the hdrcpy flag of a PDL, and returns the PDL
1366 itself. That makes it convenient for inline use in expressions.
1367
1369 Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka,
1370 (lukka@husc.harvard.edu) and Christian Soeller (c.soeller@auck‐
1371 land.ac.nz) 1997. Modified, Craig DeForest (deforest@boulder.swri.edu)
1372 2002. All rights reserved. There is no warranty. You are allowed to
1373 redistribute this software / documentation under certain conditions.
1374 For details, see the file COPYING in the PDL distribution. If this file
1375 is separated from the PDL distribution, the copyright notice should be
1376 included in the file.
1377perl v5.8.8 2002-05-21 Core(3)