1Core(3) User Contributed Perl Documentation Core(3)
2
6 PDL::Core - fundamental PDL functionality and vectorization/threading
7
9 Methods and functions for type conversions, PDL creation, type
10 conversion, threading etc.
11
13 use PDL::Core; # Normal routines
14 use PDL::Core ':Internal'; # Hairy routines
15
17 PDL provides vectorized operations via a built-in engine.
18 Vectorization is called "threading" for historical reasons. The
19 threading engine implements simple rules for each operation.
20 Each PDL object has a "shape" that is a generalized N-dimensional
22 rectangle defined by a "dim list" of sizes in an arbitrary set of
23 dimensions. A PDL with shape 2x3 has 6 elements and is said to be two-
24 dimensional, or may be referred to as a 2x3-PDL. The dimensions are
25 indexed numerically starting at 0, so a 2x3-PDL has a dimension 0 (or
26 "dim 0") with size 2 and a 1 dimension (or "dim 1") with size 3.
27 PDL generalizes *all* mathematical operations with the notion of
29 "active dims": each operator has zero or more active dims that are used
30 in carrying out the operation. Simple scalar operations like scalar
31 multiplication ('*') have 0 active dims. More complicated operators
32 can have more active dims. For example, matrix multiplication ('x')
33 has 2 active dims. Additional dims are automatically vectorized across
34 -- e.g. multiplying a 2x5-PDL with a 2x5-PDL requires 10 simple
35 multiplication operations, and yields a 2x5-PDL result.
36 Threading rules
38 In any PDL expression, the active dims appropriate for each operator
39 are used starting at the 0 dim and working forward through the dim list
40 of each object. All additional dims after the active dims are "thread
41 dims". The thread dims do not have to agree exactly: they are coerced
42 to agree according to simple rules:
43 • Null PDLs match any dim list (see below).
45 • Dims with sizes other than 1 must all agree in size.
47 • Dims of size 1 are expanded as necessary.
49 • Missing dims are expanded appropriately.
51 The "size 1" rule implements "generalized scalar" operation, by analogy
53 to scalar multiplication. The "missing dims" rule acknowledges the
54 ambiguity between a missing dim and a dim of size 1.
55 Null PDLs
57 PDLs on the left-hand side of assignment can have the special value
58 "Null". A null PDL has no dim list and no set size; its shape is
59 determined by the computed shape of the expression being assigned to
60 it. Null PDLs contain no values and can only be assigned to. When
61 assigned to (e.g. via the ".=" operator), they cease to be null PDLs.
62 To create a null PDL, use "PDL->null()".
64 Empty PDLs
66 PDLs can represent the empty set using "structured Empty" variables.
67 An empty PDL is not a null PDL.
68 Any dim of a PDL can be set explicitly to size 0. If so, the PDL
70 contains zero values (because the total number of values is the product
71 of all the sizes in the PDL's shape or dimlist).
72 Scalar PDLs are zero-dimensional and have no entries in the dim list,
74 so they cannot be empty. 1-D and higher PDLs can be empty. Empty PDLs
75 are useful for set operations, and are most commonly encountered in the
76 output from selection operators such as which and whichND. Not all
77 empty PDLs have the same threading properties -- e.g. a 2x0-PDL
78 represents a collection of 2-vectors that happens to contain no
79 elements, while a simple 0-PDL represents a collection of scalar values
80 (that also happens to contain no elements).
81 Note that 0 dims are not adjustable via the threading rules -- a dim
83 with size 0 can only match a corresponding dim of size 0 or 1.
84 Thread rules and assignments
86 Versions of PDL through 2.4.10 have some irregularity with threading
87 and assignments. Currently the threading engine performs a full
88 expansion of both sides of the computed assignment operator ".=" (which
89 assigns values to a pre-existing PDL). This leads to counter-intuitive
90 behavior in some cases:
91 • Generalized scalars and computed assignment
93 If the PDL on the left-hand side of ".=" has a dim of size 1, it can
95 be treated as a generalized scalar, as in:
96 $x = sequence(2,3);
98 $y = zeroes(1,3);
99 $y .= $x;
100 In this case, $y is automatically treated as a 2x3-PDL during the
102 threading operation, but half of the values from $x silently
103 disappear. The output is, as Kernighan and Ritchie would say,
104 "undefined".
105 Further, if the value on the right of ".=" is empty, then ".="
107 becomes a silent no-op:
108 $x = zeroes(0);
110 $y = zeroes(1);
111 $y .= $x+1;
112 print $y;
113 will print "[0]". In this case, "$x+1" is empty, and "$y" is a
115 generalized scalar that is adjusted to be empty, so the assignment
116 is carried out for zero elements (a no-op).
117 Both of these behaviors are considered harmful and should not be
119 relied upon: they may be patched away in a future version of PDL.
120 • Empty PDLs and generalized scalars
122 Generalized scalars (PDLs with a dim of size 1) can match any size
124 in the corresponding dim, including 0. Thus,
125 $x = ones(2,0);
127 $y = sequence(2,1);
128 $c = $x * $y;
129 print $c;
130 prints "Empty[2,0]".
132 This behavior is counterintuitive but desirable, and will be
134 preserved in future versions of PDL.
135
137 These are important variables of global scope and are placed in the PDL
138 namespace.
139 $PDL::debug
141 When true, PDL debugging information is printed.
143 $PDL::verbose
145 When true, PDL functions provide chatty information.
147 $PDL::use_commas
149 Whether to insert commas when printing pdls
151 $PDL::floatformat, $PDL::doubleformat, $PDL::indxformat
153 The default print format for floats, doubles, and indx values,
155 respectively. The default default values are:
156 $PDL::floatformat = "%7g";
158 $PDL::doubleformat = "%10.8g";
159 $PDL::indxformat = "%12d";
160 $PDL::undefval
162 The value to use instead of "undef" when creating pdls.
164 $PDL::toolongtoprint
166 The maximal size pdls to print (defaults to 10000 elements)
168
170 barf
171 Standard error reporting routine for PDL.
172 "barf()" is the routine PDL modules should call to report errors. This
174 is because "barf()" will report the error as coming from the correct
175 line in the module user's script rather than in the PDL module.
176 For now, barf just calls Carp::confess()
178 Remember "barf()" is your friend. *Use* it!
180 At the perl level:
182 barf("User has too low an IQ!");
184 In C or XS code:
186 barf("You have made %d errors", count);
188 Note: this is one of the few functions ALWAYS exported by PDL::Core
190 pdl
192 PDL constructor - creates new piddle from perl scalars/arrays, piddles,
193 and strings
194 $double_pdl = pdl(SCALAR|ARRAY REFERENCE|ARRAY|STRING); # default type
196 $type_pdl = pdl(PDL::Type,SCALAR|ARRAY REFERENCE|ARRAY|STRING);
197 $x = pdl [1..10]; # 1D array
199 $x = pdl ([1..10]); # 1D array
200 $x = pdl (1,2,3,4); # Ditto
201 $y = pdl [[1,2,3],[4,5,6]]; # 2D 3x2 array
202 $y = pdl "[[1,2,3],[4,5,6]]"; # Ditto (slower)
203 $y = pdl "[1 2 3; 4 5 6]"; # Ditto
204 $y = pdl q[1 2 3; 4 5 6]; # Ditto, using the q quote operator
205 $y = pdl "1 2 3; 4 5 6"; # Ditto, less obvious, but still works
206 $y = pdl 42 # 0-dimensional scalar
207 $c = pdl $x; # Make a new copy
208 $u = pdl ushort(), 42 # 0-dimensional ushort scalar
210 $y = pdl(byte(),[[1,2,3],[4,5,6]]); # 2D byte piddle
211 $n = pdl indx(), [1..5]; # 1D array of indx values
213 $n = pdl indx, [1..5]; # ... can leave off parens
214 $n = indx( [1..5] ); # ... still the same!
215 $x = pdl([1,2,3],[4,5,6]); # 2D
217 $x = pdl([1,2,3],[4,5,6]); # 2D
218 Note the last two are equivalent - a list is automatically converted to
220 a list reference for syntactic convenience. i.e. you can omit the outer
221 "[]"
222 You can mix and match arrays, array refs, and PDLs in your argument
224 list, and "pdl" will sort them out. You get back a PDL whose last
225 (slowest running) dim runs across the top level of the list you hand
226 in, and whose first (fastest running) dim runs across the deepest level
227 that you supply.
228 At the moment, you cannot mix and match those arguments with string
230 arguments, though we can't imagine a situation in which you would
231 really want to do that.
232 The string version of pdl also allows you to use the strings "bad",
234 "inf", and "nan", and it will insert the values that you mean (and set
235 the bad flag if you use "bad"). You can mix and match case, though you
236 shouldn't. Here are some examples:
237 $bad = pdl q[1 2 3 bad 5 6]; # Set fourth element to the bad value
239 $bad = pdl q[1 2 3 BAD 5 6]; # ditto
240 $bad = pdl q[1 2 inf bad 5]; # now third element is IEEE infinite value
241 $bad = pdl q[nan 2 inf -inf]; # first value is IEEE nan value
242 The default constructor uses IEEE double-precision floating point
244 numbers. You can use other types, but you will get a warning if you try
245 to use "nan" with integer types (it will be replaced with the "bad"
246 value) and you will get a fatal error if you try to use "inf".
247 Throwing a PDL into the mix has the same effect as throwing in a list
249 ref:
250 pdl(pdl(1,2),[3,4])
252 is the same as
254 pdl([1,2],[3,4]).
256 All of the dimensions in the list are "padded-out" with undefval to
258 meet the widest dim in the list, so (e.g.)
259 $x = pdl([[1,2,3],[2]])
261 gives you the same answer as
263 $x = pdl([[1,2,3],[2,undef,undef]]);
265 If your PDL module has bad values compiled into it (see PDL::Bad), you
267 can pass BAD values into the constructor within pre-existing PDLs. The
268 BAD values are automatically kept BAD and propagated correctly.
269 "pdl()" is a functional synonym for the 'new' constructor, e.g.:
271 $x = new PDL [1..10];
273 In order to control how undefs are handled in converting from perl
275 lists to PDLs, one can set the variable $PDL::undefval. For example:
276 $foo = [[1,2,undef],[undef,3,4]];
278 $PDL::undefval = -999;
279 $f = pdl $foo;
280 print $f
281 [
282 [ 1 2 -999]
283 [-999 3 4]
284 ]
285 $PDL::undefval defaults to zero.
287 As a final note, if you include an Empty PDL in the list of objects to
289 construct into a PDL, it is kept as a placeholder pane -- so if you
290 feed in (say) 7 objects, you get a size of 7 in the 0th dim of the
291 output PDL. The placeholder panes are completely padded out. But if
292 you feed in only a single Empty PDL, you get back the Empty PDL (no
293 padding).
294 null
296 Returns a 'null' piddle.
297 $x = null;
299 "null()" has a special meaning to PDL::PP. It is used to flag a special
301 kind of empty piddle, which can grow to appropriate dimensions to store
302 a result (as opposed to storing a result in an existing piddle).
303 pdl> sumover sequence(10,10), $ans=null;p $ans
305 [45 145 245 345 445 545 645 745 845 945]
306 nullcreate
308 Returns a 'null' piddle.
309 $x = PDL->nullcreate($arg)
311 This is an routine used by many of the threading primitives (i.e.
313 sumover, minimum, etc.) to generate a null piddle for the function's
314 output that will behave properly for derived (or subclassed) PDL
315 objects.
316 For the above usage: If $arg is a PDL, or a derived PDL, then
318 "$arg->null" is returned. If $arg is a scalar (i.e. a zero-dimensional
319 PDL) then "PDL->null" is returned.
320 PDL::Derived->nullcreate(10)
322 returns PDL::Derived->null.
323 PDL->nullcreate($pdlderived)
324 returns $pdlderived->null.
325 nelem
327 Return the number of elements in a piddle
328 $n = nelem($piddle); $n = $piddle->nelem;
330 $mean = sum($data)/nelem($data);
332 dims
334 Return piddle dimensions as a perl list
335 @dims = $piddle->dims; @dims = dims($piddle);
337 pdl> p @tmp = dims zeroes 10,3,22
339 10 3 22
340 See also "shape" which returns a piddle instead.
342 shape
344 Return piddle dimensions as a piddle
345 $shape = $piddle->shape; $shape = shape($piddle);
347 pdl> p $shape = shape zeroes 10,3,22
349 [10 3 22]
350 See also "dims" which returns a perl list.
352 ndims
354 Returns the number of dimensions in a piddle. Alias for getndims.
355 getndims
357 Returns the number of dimensions in a piddle
358 $ndims = $piddle->getndims;
360 pdl> p zeroes(10,3,22)->getndims
362 3
363 dim
365 Returns the size of the given dimension of a piddle. Alias for getdim.
366 getdim
368 Returns the size of the given dimension.
369 $dim0 = $piddle->getdim(0);
371 pdl> p zeroes(10,3,22)->getdim(1)
373 3
374 Negative indices count from the end of the dims array. Indices beyond
376 the end will return a size of 1. This reflects the idea that any pdl is
377 equivalent to an infinitely dimensional array in which only a finite
378 number of dimensions have a size different from one. For example, in
379 that sense a 3D piddle of shape [3,5,2] is equivalent to a
380 [3,5,2,1,1,1,1,1,....] piddle. Accordingly,
381 print $x->getdim(10000);
383 will print 1 for most practically encountered piddles.
385 topdl
387 alternate piddle constructor - ensures arg is a piddle
388 $x = topdl(SCALAR|ARRAY REFERENCE|ARRAY);
390 The difference between pdl() and "topdl()" is that the latter will just
392 'fall through' if the argument is already a piddle. It will return a
393 reference and NOT a new copy.
394 This is particularly useful if you are writing a function which is
396 doing some fiddling with internals and assumes a piddle argument (e.g.
397 for method calls). Using "topdl()" will ensure nothing breaks if passed
398 with '2'.
399 Note that "topdl()" is not exported by default (see example below for
401 usage).
402 use PDL::Core ':Internal'; # use the internal routines of
404 # the Core module
405 $x = topdl 43; # $x is piddle with value '43'
407 $y = topdl $piddle; # fall through
408 $x = topdl (1,2,3,4); # Convert 1D array
409 get_datatype
411 Internal: Return the numeric value identifying the piddle datatype
412 $x = $piddle->get_datatype;
414 Mainly used for internal routines.
416 NOTE: get_datatype returns 'just a number' not any special type object,
418 unlike "type".
419 howbig
421 Returns the sizeof a piddle datatype in bytes.
422 Note that "howbig()" is not exported by default (see example below for
424 usage).
425 use PDL::Core ':Internal'; # use the internal routines of
427 # the Core module
428 $size = howbig($piddle->get_datatype);
430 Mainly used for internal routines.
432 NOTE: NOT a method! This is because get_datatype returns 'just a
434 number' not any special object.
435 pdl> p howbig(ushort([1..10])->get_datatype)
437 2
438 get_dataref
440 Return the internal data for a piddle, as a perl SCALAR ref.
441 Most piddles hold their internal data in a packed perl string, to take
443 advantage of perl's memory management. This gives you direct access to
444 the string, which is handy when you need to manipulate the binary data
445 directly (e.g. for file I/O). If you modify the string, you'll need to
446 call "upd_data" afterward, to make sure that the piddle points to the
447 new location of the underlying perl variable.
448 Calling "get_dataref" automatically physicalizes your piddle (see
450 make_physical). You definitely don't want to do anything to the SV to
451 truncate or deallocate the string, unless you correspondingly call
452 "reshape" to make the PDL match its new data dimension.
453 You definitely don't want to use get_dataref unless you know what you
455 are doing (or are trying to find out): you can end up scrozzling memory
456 if you shrink or eliminate the string representation of the variable.
457 Here be dragons.
458 upd_data
460 Update the data pointer in a piddle to match its perl SV.
461 This is useful if you've been monkeying with the packed string
463 representation of the PDL, which you probably shouldn't be doing
464 anyway. (see "get_dataref".)
465 threadids
467 Returns the piddle thread IDs as a perl list
468 Note that "threadids()" is not exported by default (see example below
470 for usage).
471 use PDL::Core ':Internal'; # use the internal routines of
473 # the Core module
474 @ids = threadids $piddle;
476 doflow
478 Turn on/off dataflow
479 $x->doflow; doflow($x);
481 flows
483 Whether or not a piddle is indulging in dataflow
484 something if $x->flows; $hmm = flows($x);
486 new
488 new piddle constructor method
489 $x = PDL->new(SCALAR|ARRAY|ARRAY REF|STRING);
491 $x = PDL->new(42); # new from a Perl scalar
493 $x = new PDL 42; # ditto
494 $y = PDL->new(@list_of_vals); # new from Perl list
495 $y = new PDL @list_of_vals; # ditto
496 $z = PDL->new(\@list_of_vals); # new from Perl list reference
497 $w = PDL->new("[1 2 3]"); # new from Perl string, using
498 # Matlab constructor syntax
499 Constructs piddle from perl numbers and lists and strings with
501 Matlab/Octave style constructor syntax.
502 The string input is fairly versatile though not performance optimized.
504 The goal is to make it easy to copy and paste code from PDL output and
505 to offer a familiar Matlab syntax for piddle construction. As of May,
506 2010, it is a new feature, so feel free to report bugs or suggest new
507 features. See documentation for pdl for more examples of usage.
508 copy
510 Make a physical copy of a piddle
511 $new = $old->copy;
513 Since "$new = $old" just makes a new reference, the "copy" method is
515 provided to allow real independent copies to be made.
516 hdr_copy
518 Return an explicit copy of the header of a PDL.
519 hdr_copy is just a wrapper for the internal routine _hdr_copy, which
521 takes the hash ref itself. That is the routine which is used to make
522 copies of the header during normal operations if the hdrcpy() flag of a
523 PDL is set.
524 General-purpose deep copies are expensive in perl, so some simple
526 optimization happens:
527 If the header is a tied array or a blessed hash ref with an associated
529 method called "copy", then that ->copy method is called. Otherwise,
530 all elements of the hash are explicitly copied. References are
531 recursively deep copied.
532 This routine seems to leak memory.
534 unwind
536 Return a piddle which is the same as the argument except that all
537 threadids have been removed.
538 $y = $x->unwind;
540 make_physical
542 Make sure the data portion of a piddle can be accessed from XS code.
543 $x->make_physical;
545 $x->call_my_xs_method;
546 Ensures that a piddle gets its own allocated copy of data. This
548 obviously implies that there are certain piddles which do not have
549 their own data. These are so called virtual piddles that make use of
550 the vaffine optimisation (see PDL::Indexing). They do not have their
551 own copy of data but instead store only access information to some (or
552 all) of another piddle's data.
553 Note: this function should not be used unless absolutely necessary
555 since otherwise memory requirements might be severely increased.
556 Instead of writing your own XS code with the need to call
557 "make_physical" you might want to consider using the PDL preprocessor
558 (see PDL::PP) which can be used to transparently access virtual piddles
559 without the need to physicalise them (though there are exceptions).
560 dummy
562 Insert a 'dummy dimension' of given length (defaults to 1)
563 No relation to the 'Dungeon Dimensions' in Discworld!
565 Negative positions specify relative to last dimension, i.e. "dummy(-1)"
567 appends one dimension at end, "dummy(-2)" inserts a dummy dimension in
568 front of the last dim, etc.
569 If you specify a dimension position larger than the existing dimension
571 list of your PDL, the PDL gets automagically padded with extra dummy
572 dimensions so that you get the dim you asked for, in the slot you asked
573 for. This could cause you trouble if, for example, you ask for
574 $x->dummy(5000,1) because $x will get 5,000 dimensions, each of rank 1.
575 Because padding at the beginning of the dimension list moves existing
577 dimensions from slot to slot, it's considered unsafe, so automagic
578 padding doesn't work for large negative indices -- only for large
579 positive indices.
580 $y = $x->dummy($position[,$dimsize]);
582 pdl> p sequence(3)->dummy(0,3)
584 [
585 [0 0 0]
586 [1 1 1]
587 [2 2 2]
588 ]
589 pdl> p sequence(3)->dummy(3,2)
591 [
592 [
593 [0 1 2]
594 ]
595 [
596 [0 1 2]
597 ]
598 ]
599 pdl> p sequence(3)->dummy(-3,2)
601 Runtime error: PDL: For safety, <pos> < -(dims+1) forbidden in dummy. min=-2, pos=-3
602 clump
604 "clumps" several dimensions into one large dimension
605 If called with one argument $n clumps the first $n dimensions into one.
607 For example, if $x has dimensions "(5,3,4)" then after
608 $y = $x->clump(2); # Clump 2 first dimensions
610 the variable $y will have dimensions "(15,4)" and the element
612 "$y->at(7,3)" refers to the element "$x->at(1,2,3)".
613 Use "clump(-1)" to flatten a piddle. The method flat is provided as a
615 convenient alias.
616 Clumping with a negative dimension in general leaves that many
618 dimensions behind -- e.g. clump(-2) clumps all of the first few
619 dimensions into a single one, leaving a 2-D piddle.
620 If "clump" is called with an index list with more than one element it
622 is treated as a list of dimensions that should be clumped together into
623 one. The resulting clumped dim is placed at the position of the lowest
624 index in the list. This convention ensures that "clump" does the
625 expected thing in the usual cases. The following example demonstrates
626 typical usage:
627 $x = sequence 2,3,3,3,5; # 5D piddle
629 $c = $x->clump(1..3); # clump all the dims 1 to 3 into one
630 print $c->info; # resulting 3D piddle has clumped dim at pos 1
631 PDL: Double D [2,27,5]
632 thread_define
634 define functions that support threading at the perl level
635 thread_define 'tline(a(n);b(n))', over {
637 line $_[0], $_[1]; # make line compliant with threading
638 };
639 "thread_define" provides some support for threading (see PDL::Indexing)
641 at the perl level. It allows you to do things for which you normally
642 would have resorted to PDL::PP (see PDL::PP); however, it is most
643 useful to wrap existing perl functions so that the new routine supports
644 PDL threading.
645 "thread_define" is used to define new threading aware functions. Its
647 first argument is a symbolic repesentation of the new function to be
648 defined. The string is composed of the name of the new function
649 followed by its signature (see PDL::Indexing and PDL::PP) in
650 parentheses. The second argument is a subroutine that will be called
651 with the slices of the actual runtime arguments as specified by its
652 signature. Correct dimension sizes and minimal number of dimensions for
653 all arguments will be checked (assuming the rules of PDL threading, see
654 PDL::Indexing).
655 The actual work is done by the "signature" class which parses the
657 signature string, does runtime dimension checks and the routine
658 "threadover" that generates the loop over all appropriate slices of pdl
659 arguments and creates pdls as needed.
660 Similar to "pp_def" and its "OtherPars" option it is possible to define
662 the new function so that it accepts normal perl args as well as
663 piddles. You do this by using the "NOtherPars" parameter in the
664 signature. The number of "NOtherPars" specified will be passed
665 unaltered into the subroutine given as the second argument of
666 "thread_define". Let's illustrate this with an example:
667 PDL::thread_define 'triangles(inda();indb();indc()), NOtherPars => 2',
669 PDL::over {
670 ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
671 };
672 This defines a function "triangles" that takes 3 piddles as input plus
674 2 arguments which are passed into the routine unaltered. This routine
675 is used to collect lists of indices into a perl scalar that is passed
676 by reference. Each line is preceded by a prefix passed as $_[4]. Here
677 is typical usage:
678 $txt = '';
680 triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
681 print $txt;
682 resulting in the following output
684 1,1,0,-1,
686 2,1,0,-1,
687 3,1,0,-1,
688 which is used in PDL::Graphics::TriD::VRML to generate VRML output.
690 Currently, this is probably not much more than a POP (proof of
692 principle) but is hoped to be useful enough for some real life work.
693 Check PDL::PP for the format of the signature. Currently, the "[t]"
695 qualifier and all type qualifiers are ignored.
696 thread
698 Use explicit threading over specified dimensions (see also
699 PDL::Indexing)
700 $y = $x->thread($dim,[$dim1,...])
702 $x = zeroes 3,4,5;
704 $y = $x->thread(2,0);
705 Same as "PDL::thread1", i.e. uses thread id 1.
707 diagonal
709 Returns the multidimensional diagonal over the specified dimensions.
710 $d = $x->diagonal(dim1, dim2,...)
712 pdl> $x = zeroes(3,3,3);
714 pdl> ($y = $x->diagonal(0,1))++;
715 pdl> p $x
716 [
717 [
718 [1 0 0]
719 [0 1 0]
720 [0 0 1]
721 ]
722 [
723 [1 0 0]
724 [0 1 0]
725 [0 0 1]
726 ]
727 [
728 [1 0 0]
729 [0 1 0]
730 [0 0 1]
731 ]
732 ]
733 thread1
735 Explicit threading over specified dims using thread id 1.
736 $xx = $x->thread1(3,1)
738 Wibble
740 Convenience function interfacing to PDL::Slices::threadI.
742 thread2
744 Explicit threading over specified dims using thread id 2.
745 $xx = $x->thread2(3,1)
747 Wibble
749 Convenience function interfacing to PDL::Slices::threadI.
751 thread3
753 Explicit threading over specified dims using thread id 3.
754 $xx = $x->thread3(3,1)
756 Wibble
758 Convenience function interfacing to PDL::Slices::threadI.
760 sever
762 sever any links of this piddle to parent piddles
763 In PDL it is possible for a piddle to be just another view into another
765 piddle's data. In that case we call this piddle a virtual piddle and
766 the original piddle owning the data its parent. In other languages
767 these alternate views sometimes run by names such as alias or smart
768 reference.
769 Typical functions that return such piddles are "slice", "xchg",
771 "index", etc. Sometimes, however, you would like to separate the
772 virtual piddle from its parent's data and just give it a life of its
773 own (so that manipulation of its data doesn't change the parent). This
774 is simply achieved by using "sever". For example,
775 $x = $pdl->index(pdl(0,3,7))->sever;
777 $x++; # important: $pdl is not modified!
778 In many (but not all) circumstances it acts therefore similar to copy.
780 However, in general performance is better with "sever" and secondly,
781 "sever" doesn't lead to futile copying when used on piddles that
782 already have their own data. On the other hand, if you really want to
783 make sure to work on a copy of a piddle use copy.
784 $x = zeroes(20);
786 $x->sever; # NOOP since $x is already its own boss!
787 Again note: "sever" is not the same as copy! For example,
789 $x = zeroes(1); # $x does not have a parent, i.e. it is not a slice etc
791 $y = $x->sever; # $y is now pointing to the same piddle as $x
792 $y++;
793 print $x;
794 [1]
795 but
797 $x = zeroes(1);
799 $y = $x->copy; # $y is now pointing to a new piddle
800 $y++;
801 print $x;
802 [0]
803 info
805 Return formatted information about a piddle.
806 $x->info($format_string);
808 print $x->info("Type: %T Dim: %-15D State: %S");
810 Returns a string with info about a piddle. Takes an optional argument
812 to specify the format of information a la sprintf. Format specifiers
813 are in the form "%<width><letter>" where the width is optional and the
814 letter is one of
815 T Type
817 D Formatted Dimensions
819 F Dataflow status
821 S Some internal flags (P=physical,V=Vaffine,C=changed,B=may
823 contain bad data)
824 C Class of this piddle, i.e. "ref $pdl"
826 A Address of the piddle struct as a unique identifier
828 M Calculated memory consumption of this piddle's data area
830 approx
832 test for approximately equal values (relaxed "==")
833 # ok if all corresponding values in
835 # piddles are within 1e-8 of each other
836 print "ok\n" if all approx $x, $y, 1e-8;
837 "approx" is a relaxed form of the "==" operator and often more
839 appropriate for floating point types ("float" and "double").
840 Usage:
842 $res = approx $x, $y [, $eps]
844 The optional parameter $eps is remembered across invocations and
846 initially set to 1e-6, e.g.
847 approx $x, $y; # last $eps used (1e-6 initially)
849 approx $x, $y, 1e-10; # 1e-10
850 approx $x, $y; # also 1e-10
851 mslice
853 Convenience interface to slice, allowing easier inclusion of dimensions
854 in perl code.
855 $w = $x->mslice(...);
857 # below is the same as $x->slice("5:7,:,3:4:2")
859 $w = $x->mslice([5,7],X,[3,4,2]);
860 nslice_if_pdl
862 If $self is a PDL, then calls "slice" with all but the last argument,
863 otherwise $self->($_[-1]) is called where $_[-1} is the original
864 argument string found during PDL::NiceSlice filtering.
865 DEVELOPER'S NOTE: this routine is found in Core.pm.PL but would be
867 better placed in Slices/slices.pd. It is likely to be moved there
868 and/or changed to "slice_if_pdl" for PDL 3.0.
869 $w = $x->nslice_if_pdl(...,'(args)');
871 nslice
873 "nslice" was an internally used interface for PDL::NiceSlice, but is
874 now merely a springboard to PDL::Slices. It is deprecated and likely
875 to disappear in PDL 3.0.
876 inplace
878 Flag a piddle so that the next operation is done 'in place'
879 somefunc($x->inplace); somefunc(inplace $x);
881 In most cases one likes to use the syntax "$y = f($x)", however in many
883 case the operation "f()" can be done correctly 'in place', i.e. without
884 making a new copy of the data for output. To make it easy to use this,
885 we write "f()" in such a way that it operates in-place, and use
886 "inplace" to hint that a new copy should be disabled. This also makes
887 for clear syntax.
888 Obviously this will not work for all functions, and if in doubt see the
890 function's documentation. However one can assume this is true for all
891 elemental functions (i.e. those which just operate array element by
892 array element like "log10").
893 pdl> $x = xvals zeroes 10;
895 pdl> log10(inplace $x)
896 pdl> p $x
897 [-inf 0 0.30103 0.47712125 0.60205999 0.69897 0.77815125 0.84509804 0.90308999 0.95424251]
898 is_inplace
900 Test the in-place flag on a piddle
901 $out = ($in->is_inplace) ? $in : zeroes($in);
903 $in->set_inplace(0)
904 Provides access to the "inplace" hint flag, within the perl millieu.
906 That way functions you write can be inplace aware... If given an
907 argument the inplace flag will be set or unset depending on the value
908 at the same time. Can be used for shortcut tests that delete the
909 inplace flag while testing:
910 $out = ($in->is_inplace(0)) ? $in : zeroes($in); # test & unset!
912 set_inplace
914 Set the in-place flag on a piddle
915 $out = ($in->is_inplace) ? $in : zeroes($in);
917 $in->set_inplace(0);
918 Provides access to the "inplace" hint flag, within the perl millieu.
920 Useful mainly for turning it OFF, as "inplace" turns it ON more
921 conveniently.
922 new_or_inplace
924 $w = new_or_inplace(shift());
925 $w = new_or_inplace(shift(),$preferred_type);
926 Return back either the argument pdl or a copy of it depending on
928 whether it be flagged in-place or no. Handy for building inplace-aware
929 functions.
930 If you specify a preferred type (must be one of the usual PDL type
932 strings, a list ref containing several of them, or a string containing
933 several of them), then the copy is coerced into the first preferred
934 type listed if it is not already one of the preferred types.
935 Note that if the inplace flag is set, no coersion happens even if you
937 specify a preferred type.
938 new_from_specification
940 Internal method: create piddle by specification
941 This is the argument processing method called by "zeroes" and some
943 other functions which constructs piddles from argument lists of the
944 form:
945 [type], $nx, $ny, $nz,...
947 For $nx, $ny, etc. 0 and 1D piddles are allowed. Giving those has the
949 same effect as if saying "$arg->list", e.g.
950 1, pdl(5,2), 4
952 is equivalent to
954 1, 5, 2, 4
956 Note, however, that in all functions using "new_from_specification"
958 calling "func $piddle" will probably not do what you want. So to play
959 safe use (e.g. with zeroes)
960 $pdl = zeroes $dimpdl->list;
962 Calling
964 $pdl = zeroes $dimpdl;
966 will rather be equivalent to
968 $pdl = zeroes $dimpdl->dims;
970 However,
972 $pdl = zeroes ushort, $dimpdl;
974 will again do what you intended since it is interpreted as if you had
976 said
977 $pdl = zeroes ushort, $dimpdl->list;
979 This is unfortunate and confusing but no good solution seems obvious
981 that would not break existing scripts.
982 isnull
984 Test whether a piddle is null
985 croak("Input piddle mustn't be null!")
987 if $input_piddle->isnull;
988 This function returns 1 if the piddle is null, zero if it is not. The
990 purpose of null piddles is to "tell" any PDL::PP methods to allocate
991 new memory for an output piddle, but only when that PDL::PP method is
992 called in full-arg form. Of course, there's no reason you couldn't
993 commandeer the special value for your own purposes, for which this test
994 function would prove most helpful. But in general, you shouldn't need
995 to test for a piddle's nullness.
996 See "Null PDLs" for more information.
998 isempty
1000 Test whether a piddle is empty
1001 print "The piddle has zero dimension\n" if $pdl->isempty;
1003 This function returns 1 if the piddle has zero elements. This is useful
1005 in particular when using the indexing function which. In the case of no
1006 match to a specified criterion, the returned piddle has zero dimension.
1007 pdl> $w=sequence(10)
1009 pdl> $i=which($w < -1)
1010 pdl> print "I found no matches!\n" if ($i->isempty);
1011 I found no matches!
1012 Note that having zero elements is rather different from the concept of
1014 being a null piddle, see the PDL::FAQ and PDL::Indexing manpages for
1015 discussions of this.
1016 zeroes
1018 construct a zero filled piddle from dimension list or template piddle.
1019 Various forms of usage,
1021 (i) by specification or (ii) by template piddle:
1023 # usage type (i):
1025 $w = zeroes([type], $nx, $ny, $nz,...);
1026 $w = PDL->zeroes([type], $nx, $ny, $nz,...);
1027 $w = $pdl->zeroes([type], $nx, $ny, $nz,...);
1028 # usage type (ii):
1029 $w = zeroes $y;
1030 $w = $y->zeroes
1031 zeroes inplace $w; # Equivalent to $w .= 0;
1032 $w->inplace->zeroes; # ""
1033 pdl> $z = zeroes 4,3
1035 pdl> p $z
1036 [
1037 [0 0 0 0]
1038 [0 0 0 0]
1039 [0 0 0 0]
1040 ]
1041 pdl> $z = zeroes ushort, 3,2 # Create ushort array
1042 [ushort() etc. with no arg returns a PDL::Types token]
1043 See also new_from_specification for details on using piddles in the
1045 dimensions list.
1046 zeros
1048 construct a zero filled piddle (see zeroes for usage)
1049 ones
1051 construct a one filled piddle
1052 $w = ones([type], $nx, $ny, $nz,...);
1054 etc. (see 'zeroes')
1055 see zeroes() and add one
1057 See also new_from_specification for details on using piddles in the
1059 dimensions list.
1060 reshape
1062 Change the shape (i.e. dimensions) of a piddle, preserving contents.
1063 $x->reshape(NEWDIMS); reshape($x, NEWDIMS);
1065 The data elements are preserved, obviously they will wrap differently
1067 and get truncated if the new array is shorter. If the new array is
1068 longer it will be zero-padded.
1069 ***Potential incompatibility with earlier versions of PDL**** If the
1071 list of "NEWDIMS" is empty "reshape" will just drop all dimensions of
1072 size 1 (preserving the number of elements):
1073 $w = sequence(3,4,5);
1075 $y = $w(1,3);
1076 $y->reshape();
1077 print $y->info;
1078 PDL: Double D [5]
1079 Dimensions of size 1 will also be dropped if "reshape" is invoked with
1081 the argument -1:
1082 $y = $w->reshape(-1);
1084 As opposed to "reshape" without arguments, "reshape(-1)" preserves
1086 dataflow:
1087 $w = ones(2,1,2);
1089 $y = $w(0)->reshape(-1);
1090 $y++;
1091 print $w;
1092 [
1093 [
1094 [2 1]
1095 ]
1096 [
1097 [2 1]
1098 ]
1099 ]
1100 Important: Piddles are changed inplace!
1102 Note: If $x is connected to any other PDL (e.g. if it is a slice) then
1104 the connection is first severed.
1105 pdl> $x = sequence(10)
1107 pdl> reshape $x,3,4; p $x
1108 [
1109 [0 1 2]
1110 [3 4 5]
1111 [6 7 8]
1112 [9 0 0]
1113 ]
1114 pdl> reshape $x,5; p $x
1115 [0 1 2 3 4]
1116 squeeze
1118 eliminate all singleton dimensions (dims of size 1)
1119 $y = $w(0,0)->squeeze;
1121 Alias for "reshape(-1)". Removes all singleton dimensions and preserves
1123 dataflow. A more concise interface is provided by PDL::NiceSlice via
1124 modifiers:
1125 use PDL::NiceSlice;
1127 $y = $w(0,0;-); # same as $w(0,0)->squeeze
1128 flat
1130 flatten a piddle (alias for "$pdl->clump(-1)")
1131 $srt = $pdl->flat->qsort;
1133 Useful method to make a 1D piddle from an arbitrarily sized input
1135 piddle. Data flows back and forth as usual with slicing routines.
1136 Falls through if argument already <= 1D.
1137 convert
1139 Generic datatype conversion function
1140 $y = convert($x, $newtypenum);
1142 $y = convert $x, long
1144 $y = convert $x, ushort
1145 $newtype is a type number, for convenience they are returned by
1147 "long()" etc when called without arguments.
1148 Datatype_conversions
1150 byte|short|ushort|long|indx|longlong|float|double (shorthands to
1151 convert datatypes)
1152 $y = double $x; $y = ushort [1..10];
1154 # all of the above listed shorthands behave similarly
1155 When called with a piddle argument, they convert to the specific
1157 datatype.
1158 When called with a numeric, list, listref, or string argument they
1160 construct a new piddle. This is a convenience to avoid having to be
1161 long-winded and say "$x = long(pdl(42))"
1162 Thus one can say:
1164 $w = float(1,2,3,4); # 1D
1166 $w = float q[1 2 3; 4 5 6]; # 2D
1167 $w = float([1,2,3],[4,5,6]); # 2D
1168 $w = float([[1,2,3],[4,5,6]]); # 2D
1169 Note the last three give identical results, and the last two are
1171 exactly equivalent - a list is automatically converted to a list
1172 reference for syntactic convenience. i.e. you can omit the outer "[]"
1173 When called with no arguments, these functions return a special type
1175 token. This allows syntactical sugar like:
1176 $x = ones byte, 1000,1000;
1178 This example creates a large piddle directly as byte datatype in order
1180 to save memory.
1181 In order to control how undefs are handled in converting from perl
1183 lists to PDLs, one can set the variable $PDL::undefval; see the
1184 function pdl() for more details.
1185 pdl> p $x=sqrt float [1..10]
1187 [1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228]
1188 pdl> p byte $x
1189 [1 1 1 2 2 2 2 2 3 3]
1190 byte
1192 Convert to byte datatype
1193 short
1195 Convert to short datatype
1196 ushort
1198 Convert to ushort datatype
1199 long
1201 Convert to long datatype
1202 indx
1204 Convert to indx datatype
1205 longlong
1207 Convert to longlong datatype
1208 float
1210 Convert to float datatype
1211 double
1213 Convert to double datatype
1214 type
1216 return the type of a piddle as a blessed type object
1217 A convenience function for use with the piddle constructors, e.g.
1219 $y = PDL->zeroes($x->type,$x->dims,3);
1221 die "must be float" unless $x->type == float;
1222 See also the discussion of the "PDL::Type" class in PDL::Types. Note
1224 that the "PDL::Type" objects have overloaded comparison and stringify
1225 operators so that you can compare and print types:
1226 $x = $x->float if $x->type < float;
1228 $t = $x->type; print "Type is $t\";
1229 list
1231 Convert piddle to perl list
1232 @tmp = list $x;
1234 Obviously this is grossly inefficient for the large datasets PDL is
1236 designed to handle. This was provided as a get out while PDL matured.
1237 It should now be mostly superseded by superior constructs, such as
1238 PP/threading. However it is still occasionally useful and is provied
1239 for backwards compatibility.
1240 for (list $x) {
1242 # Do something on each value...
1243 }
1244 If you compile PDL with bad value support (the default), your machine's
1246 docs will also say this:
1247 list converts any bad values into the string 'BAD'.
1249 unpdl
1251 Convert piddle to nested Perl array references
1252 $arrayref = unpdl $x;
1254 This function returns a reference to a Perl list-of-lists structure
1256 equivalent to the input piddle (within the limitation that while values
1257 of elements should be preserved, the detailed datatypes will not as
1258 perl itself basically has "number" data rather than byte, short, int...
1259 E.g., "sum($x - pdl( $x->unpdl ))" should equal 0.
1260 Obviously this is grossly inefficient in memory and processing for the
1262 large datasets PDL is designed to handle. Sometimes, however, you
1263 really want to move your data back to Perl, and with proper
1264 dimensionality, unlike "list".
1265 use JSON;
1267 my $json = encode_json unpdl $pdl;
1268 If you compile PDL with bad value support (the default), your machine's
1270 docs will also say this:
1271 unpdl converts any bad values into the string 'BAD'.
1273 listindices
1275 Convert piddle indices to perl list
1276 @tmp = listindices $x;
1278 @tmp now contains the values "0..nelem($x)".
1280 Obviously this is grossly inefficient for the large datasets PDL is
1282 designed to handle. This was provided as a get out while PDL matured.
1283 It should now be mostly superseded by superior constructs, such as
1284 PP/threading. However it is still occasionally useful and is provied
1285 for backwards compatibility.
1286 for $i (listindices $x) {
1288 # Do something on each value...
1289 }
1290 set
1292 Set a single value inside a piddle
1293 set $piddle, @position, $value
1295 @position is a coordinate list, of size equal to the number of
1297 dimensions in the piddle. Occasionally useful, mainly provided for
1298 backwards compatibility as superseded by use of slice and assignment
1299 operator ".=".
1300 pdl> $x = sequence 3,4
1302 pdl> set $x, 2,1,99
1303 pdl> p $x
1304 [
1305 [ 0 1 2]
1306 [ 3 4 99]
1307 [ 6 7 8]
1308 [ 9 10 11]
1309 ]
1310 at
1312 Returns a single value inside a piddle as perl scalar.
1313 $z = at($piddle, @position); $z=$piddle->at(@position);
1315 @position is a coordinate list, of size equal to the number of
1317 dimensions in the piddle. Occasionally useful in a general context,
1318 quite useful too inside PDL internals.
1319 pdl> $x = sequence 3,4
1321 pdl> p $x->at(1,2)
1322 7
1323 If you compile PDL with bad value support (the default), your machine's
1325 docs will also say this:
1326 at converts any bad values into the string 'BAD'.
1328 sclr
1330 return a single value from a piddle as a scalar
1331 $val = $x(10)->sclr;
1333 $val = sclr inner($x,$y);
1334 The "sclr" method is useful to turn a piddle into a normal Perl scalar.
1336 Its main advantage over using "at" for this purpose is the fact that
1337 you do not need to worry if the piddle is 0D, 1D or higher dimensional.
1338 Using "at" you have to supply the correct number of zeroes, e.g.
1339 $x = sequence(10);
1341 $y = $x->slice('4');
1342 print $y->sclr; # no problem
1343 print $y->at(); # error: needs at least one zero
1344 "sclr" is generally used when a Perl scalar is required instead of a
1346 one-element piddle. If the input is a multielement piddle the first
1347 value is returned as a Perl scalar. You can optionally switch on checks
1348 to ensure that the input piddle has only one element:
1349 PDL->sclr({Check => 'warn'}); # carp if called with multi-el pdls
1351 PDL->sclr({Check => 'barf'}); # croak if called with multi-el pdls
1352 are the commands to switch on warnings or raise an error if a
1354 multielement piddle is passed as input. Note that these options can
1355 only be set when "sclr" is called as a class method (see example
1356 above). Use
1357 PDL->sclr({Check=>0});
1359 to switch these checks off again (default setting); When called as a
1361 class method the resulting check mode is returned (0: no checking, 1:
1362 warn, 2: barf).
1363 cat
1365 concatenate piddles to N+1 dimensional piddle
1366 Takes a list of N piddles of same shape as argument, returns a single
1368 piddle of dimension N+1.
1369 pdl> $x = cat ones(3,3),zeroes(3,3),rvals(3,3); p $x
1371 [
1372 [
1373 [1 1 1]
1374 [1 1 1]
1375 [1 1 1]
1376 ]
1377 [
1378 [0 0 0]
1379 [0 0 0]
1380 [0 0 0]
1381 ]
1382 [
1383 [1 1 1]
1384 [1 0 1]
1385 [1 1 1]
1386 ]
1387 ]
1388 If you compile PDL with bad value support (the default), your machine's
1390 docs will also say this:
1391 The output piddle is set bad if any input piddles have their bad flag
1393 set.
1394 Similar functions include append, which appends only two piddles along
1396 their first dimension, and glue, which can append more than two piddles
1397 along an arbitrary dimension.
1398 Also consider the generic constructor "pdl", which can handle piddles
1400 of different sizes (with zero-padding), and will return a piddle of
1401 type 'double' by default, but may be considerably faster (up to 10x)
1402 than cat.
1403 dog
1405 Opposite of 'cat' :). Split N dim piddle to list of N-1 dim piddles
1406 Takes a single N-dimensional piddle and splits it into a list of N-1
1408 dimensional piddles. The breakup is done along the last dimension.
1409 Note the dataflown connection is still preserved by default, e.g.:
1410 pdl> $p = ones 3,3,3
1412 pdl> ($x,$y,$c) = dog $p
1413 pdl> $y++; p $p
1414 [
1415 [
1416 [1 1 1]
1417 [1 1 1]
1418 [1 1 1]
1419 ]
1420 [
1421 [2 2 2]
1422 [2 2 2]
1423 [2 2 2]
1424 ]
1425 [
1426 [1 1 1]
1427 [1 1 1]
1428 [1 1 1]
1429 ]
1430 ]
1431 Break => 1 Break dataflow connection (new copy)
1433 If you compile PDL with bad value support (the default), your machine's
1435 docs will also say this:
1436 The output piddles are set bad if the original piddle has its bad flag
1438 set.
1439 gethdr
1441 Retrieve header information from a piddle
1442 $pdl=rfits('file.fits');
1444 $h=$pdl->gethdr;
1445 print "Number of pixels in the X-direction=$$h{NAXIS1}\n";
1446 The "gethdr" function retrieves whatever header information is
1448 contained within a piddle. The header can be set with "sethdr" and is
1449 always a hash reference or undef.
1450 "gethdr" returns undef if the piddle has not yet had a header defined;
1452 compare with "hdr" and "fhdr", which are guaranteed to return a defined
1453 value.
1454 Note that gethdr() works by reference: you can modify the header in-
1456 place once it has been retrieved:
1457 $x = rfits($filename);
1459 $xh = $x->gethdr();
1460 $xh->{FILENAME} = $filename;
1461 It is also important to realise that in most cases the header is not
1463 automatically copied when you copy the piddle. See "hdrcpy" to enable
1464 automatic header copying.
1465 Here's another example: a wrapper around rcols that allows your piddle
1467 to remember the file it was read from and the columns could be easily
1468 written (here assuming that no regexp is needed, extensions are left as
1469 an exercise for the reader)
1470 sub ext_rcols {
1472 my ($file, @columns)=@_;
1473 my $header={};
1474 $$header{File}=$file;
1475 $$header{Columns}=\@columns;
1476 @piddles=rcols $file, @columns;
1478 foreach (@piddles) { $_->sethdr($header); }
1479 return @piddles;
1480 }
1481 hdr
1483 Retrieve or set header information from a piddle
1484 $pdl->hdr->{CDELT1} = 1;
1486 The "hdr" function allows convenient access to the header of a piddle.
1488 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1489 use it in a hash dereference as in the example. If the header does not
1490 yet exist, it gets autogenerated as an empty hash.
1491 Note that this is usually -- but not always -- What You Want. If you
1493 want to use a tied Astro::FITS::Header hash, for example, you should
1494 either construct it yourself and use "sethdr" to put it into the
1495 piddle, or use "fhdr" instead. (Note that you should be able to write
1496 out the FITS file successfully regardless of whether your PDL has a
1497 tied FITS header object or a vanilla hash).
1498 fhdr
1500 Retrieve or set FITS header information from a piddle
1501 $pdl->fhdr->{CDELT1} = 1;
1503 The "fhdr" function allows convenient access to the header of a piddle.
1505 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1506 use it in a hash dereference as in the example. If the header does not
1507 yet exist, it gets autogenerated as a tied Astro::FITS::Header hash.
1508 Astro::FITS::Header tied hashes are better at matching the behavior of
1510 FITS headers than are regular hashes. In particular, the hash keys are
1511 CAsE INsEnSItiVE, unlike normal hash keys. See Astro::FITS::Header for
1512 details.
1513 If you do not have Astro::FITS::Header installed, you get back a normal
1515 hash instead of a tied object.
1516 sethdr
1518 Set header information of a piddle
1519 $pdl = zeroes(100,100);
1521 $h = {NAXIS=>2, NAXIS1=>100, NAXIS=>100, COMMENT=>"Sample FITS-style header"};
1522 # add a FILENAME field to the header
1523 $$h{FILENAME} = 'file.fits';
1524 $pdl->sethdr( $h );
1525 The "sethdr" function sets the header information for a piddle. You
1527 must feed in a hash ref or undef, and the header field of the PDL is
1528 set to be a new ref to the same hash (or undefined).
1529 The hash ref requirement is a speed bump put in place since the normal
1531 use of headers is to store fits header information and the like. Of
1532 course, if you want you can hang whatever ugly old data structure you
1533 want off of the header, but that makes life more complex.
1534 Remember that the hash is not copied -- the header is made into a ref
1536 that points to the same underlying data. To get a real copy without
1537 making any assumptions about the underlying data structure, you can use
1538 one of the following:
1539 use PDL::IO::Dumper;
1541 $pdl->sethdr( deep_copy($h) );
1542 (which is slow but general), or
1544 $pdl->sethdr( PDL::_hdr_copy($h) )
1546 (which uses the built-in sleazy deep copier), or (if you know that all
1548 the elements happen to be scalars):
1549 { my %a = %$h;
1551 $pdl->sethdr(\%a);
1552 }
1553 which is considerably faster but just copies the top level.
1555 The "sethdr" function must be given a hash reference or undef. For
1557 further information on the header, see "gethdr", "hdr", "fhdr" and
1558 "hdrcpy".
1559 hdrcpy
1561 switch on/off/examine automatic header copying
1562 print "hdrs will be copied" if $x->hdrcpy;
1564 $x->hdrcpy(1); # switch on automatic header copying
1565 $y = $x->sumover; # and $y will inherit $x's hdr
1566 $x->hdrcpy(0); # and now make $x non-infectious again
1567 "hdrcpy" without an argument just returns the current setting of the
1569 flag. See also "hcpy" which returns its PDL argument (and so is useful
1570 in method-call pipelines).
1571 Normally, the optional header of a piddle is not copied automatically
1573 in pdl operations. Switching on the hdrcpy flag using the "hdrcpy"
1574 method will enable automatic hdr copying. Note that an actual deep copy
1575 gets made, which is rather processor-inefficient -- so avoid using
1576 header copying in tight loops!
1577 Most PDLs have the "hdrcpy" flag cleared by default; however, some
1579 routines (notably rfits) set it by default where that makes more sense.
1580 The "hdrcpy" flag is viral: if you set it for a PDL, then derived PDLs
1582 will get copies of the header and will also have their "hdrcpy" flags
1583 set. For example:
1584 $x = xvals(50,50);
1586 $x->hdrcpy(1);
1587 $x->hdr->{FOO} = "bar";
1588 $y = $x++;
1589 $c = $y++;
1590 print $y->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1591 $y->hdr->{FOO} = "baz";
1592 print $x->hdr->{FOO}, " - ", $y->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1593 will print:
1595 bar - bar
1597 bar - baz - bar
1598 Performing an operation in which more than one PDL has its hdrcpy flag
1600 causes the resulting PDL to take the header of the first PDL:
1601 ($x,$y) = sequence(5,2)->dog;
1603 $x->hdrcpy(1); $y->hdrcpy(1);
1604 $x->hdr->{foo} = 'a';
1605 $y->hdr->{foo} = 'b';
1606 print (($x+$y)->hdr->{foo} , ($y+$x)->hdr->{foo});
1607 will print:
1609 a b
1611 hcpy
1613 Switch on/off automatic header copying, with PDL pass-through
1614 $x = rfits('foo.fits')->hcpy(0);
1616 $x = rfits('foo.fits')->hcpy(1);
1617 "hcpy" sets or clears the hdrcpy flag of a PDL, and returns the PDL
1619 itself. That makes it convenient for inline use in expressions.
1620 set_autopthread_targ
1622 Set the target number of processor threads (pthreads) for multi-
1623 threaded processing.
1624 set_autopthread_targ($num_pthreads);
1626 $num_pthreads is the target number of pthreads the auto-pthread process
1628 will try to achieve.
1629 See PDL::ParallelCPU for an overview of the auto-pthread process.
1631 # Example turning on auto-pthreading for a target of 2 pthreads and for functions involving
1633 # PDLs with greater than 1M elements
1634 set_autopthread_targ(2);
1635 set_autopthread_size(1);
1636 # Execute a pdl function, processing will split into two pthreads as long as
1638 # one of the pdl-threaded dimensions is divisible by 2.
1639 $x = minimum($y);
1640 # Get the actual number of pthreads that were run.
1642 $actual_pthread = get_autopthread_actual();
1643 get_autopthread_targ
1645 Get the current target number of processor threads (pthreads) for
1646 multi-threaded processing.
1647 $num_pthreads = get_autopthread_targ();
1649 $num_pthreads is the target number of pthreads the auto-pthread process
1651 will try to achieve.
1652 See PDL::ParallelCPU for an overview of the auto-pthread process.
1654 get_autopthread_actual
1656 Get the actual number of pthreads executed for the last pdl processing
1657 function.
1658 $autopthread_actual = get_autopthread_actual();
1660 $autopthread_actual is the actual number of pthreads executed for the
1662 last pdl processing function.
1663 See PDL::ParallelCPU for an overview of the auto-pthread process.
1665 set_autopthread_size
1667 Set the minimum size (in M-elements or 2^20 elements) of the largest
1668 PDL involved in a function where auto-pthreading will be performed. For
1669 small PDLs, it probably isn't worth starting multiple pthreads, so this
1670 function is used to define a minimum threshold where auto-pthreading
1671 won't be attempted.
1672 set_autopthread_size($size);
1674 $size is the mimumum size, in M-elements or 2^20 elements (approx 1e6
1676 elements) for the largest PDL involved in a function.
1677 See PDL::ParallelCPU for an overview of the auto-pthread process.
1679 # Example turning on auto-pthreading for a target of 2 pthreads and for functions involving
1681 # PDLs with greater than 1M elements
1682 set_autopthread_targ(2);
1683 set_autopthread_size(1);
1684 # Execute a pdl function, processing will split into two pthreads as long as
1686 # one of the pdl-threaded dimensions is divisible by 2.
1687 $x = minimum($y);
1688 # Get the actual number of pthreads that were run.
1690 $actual_pthread = get_autopthread_actual();
1691 get_autopthread_size
1693 Get the current autopthread_size setting.
1694 $autopthread_size = get_autopthread_size();
1696 $autopthread_size is the mimumum size limit for auto_pthreading to
1698 occur, in M-elements or 2^20 elements (approx 1e6 elements) for the
1699 largest PDL involved in a function
1700 See PDL::ParallelCPU for an overview of the auto-pthread process.
1702
1704 Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka,
1705 (lukka@husc.harvard.edu) and Christian Soeller
1706 (c.soeller@auckland.ac.nz) 1997. Modified, Craig DeForest
1707 (deforest@boulder.swri.edu) 2002. All rights reserved. There is no
1708 warranty. You are allowed to redistribute this software / documentation
1709 under certain conditions. For details, see the file COPYING in the PDL
1710 distribution. If this file is separated from the PDL distribution, the
1711 copyright notice should be included in the file.
1712perl v5.32.1 2021-02-15 Core(3)