1Core(3)               User Contributed Perl Documentation              Core(3)
2
3
4

NAME

6       PDL::Core - fundamental PDL functionality and vectorization/threading
7

DESCRIPTION

9       Methods and functions for type conversions, PDL creation, type
10       conversion, threading etc.
11

SYNOPSIS

13        use PDL::Core;             # Normal routines
14        use PDL::Core ':Internal'; # Hairy routines
15

VECTORIZATION/THREADING: METHOD AND NOMENCLATURE

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
21       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
28       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
37   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
44       ·  Null PDLs match any dim list (see below).
45
46       ·  Dims with sizes other than 1 must all agree in size.
47
48       ·  Dims of size 1 are expanded as necessary.
49
50       ·  Missing dims are expanded appropriately.
51
52       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
56   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
63       To create a null PDL, use "PDL->null()".
64
65   Empty PDLs
66       PDLs can represent the empty set using "structured Empty" variables.
67       An empty PDL is not a null PDL.
68
69       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
73       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
82       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
85   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
92       ·  Generalized scalars and computed assignment
93
94          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
97              $a = sequence(2,3);
98              $b = zeroes(1,3);
99              $b .= $a;
100
101          In this case, $b is automatically treated as a 2x3-PDL during the
102          threading operation, but half of the values from $a silently
103          disappear.  The output is, as Kernighan and Ritchie would say,
104          "undefined".
105
106          Further, if the value on the right of ".=" is empty, then ".="
107          becomes a silent no-op:
108
109              $a = zeroes(0);
110              $b = zeroes(1);
111              $b .= $a+1;
112              print $b;
113
114          will print "[0]".  In this case, "$a+1" is empty, and "$b" 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
118          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
121       ·  Empty PDLs and generalized scalars
122
123          Generalized scalars (PDLs with a dim of size 1) can match any size
124          in the corresponding dim, including 0.  Thus,
125
126              $a = ones(2,0);
127              $b = sequence(2,1);
128              $c = $a * $b;
129              print $c;
130
131          prints "Empty[2,0]".
132
133          This behavior is counterintuitive but desirable, and will be
134          preserved in future versions of PDL.
135

VARIABLES

137       These are important variables of global scope and are placed in the PDL
138       namespace.
139
140       $PDL::debug
141
142           When true, PDL debugging information is printed.
143
144       $PDL::verbose
145
146           When true, PDL functions provide chatty information.
147
148       $PDL::use_commas
149
150           Whether to insert commas when printing pdls
151
152       $PDL::floatformat, $PDL::doubleformat, $PDL::indxformat
153
154           The default print format for floats, doubles, and indx values,
155           respectively.  The default default values are:
156
157             $PDL::floatformat  = "%7g";
158             $PDL::doubleformat = "%10.8g";
159             $PDL::indxformat   = "%12d";
160
161       $PDL::undefval
162
163           The value to use instead of "undef" when creating pdls.
164
165       $PDL::toolongtoprint
166
167           The maximal size pdls to print (defaults to 10000 elements)
168

FUNCTIONS

170   barf
171       Standard error reporting routine for PDL.
172
173       "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
177       For now, barf just calls Carp::confess()
178
179       Remember "barf()" is your friend. *Use* it!
180
181       At the perl level:
182
183        barf("User has too low an IQ!");
184
185       In C or XS code:
186
187        barf("You have made %d errors", count);
188
189       Note: this is one of the few functions ALWAYS exported by PDL::Core
190
191   pdl
192       PDL constructor - creates new piddle from perl scalars/arrays, piddles,
193       and strings
194
195        $double_pdl = pdl(SCALAR|ARRAY REFERENCE|ARRAY|STRING);  # default type
196        $type_pdl   = pdl(PDL::Type,SCALAR|ARRAY REFERENCE|ARRAY|STRING);
197
198        $a = pdl [1..10];                    # 1D array
199        $a = pdl ([1..10]);                  # 1D array
200        $a = pdl (1,2,3,4);                  # Ditto
201        $b = pdl [[1,2,3],[4,5,6]];          # 2D 3x2 array
202        $b = pdl "[[1,2,3],[4,5,6]]";        # Ditto (slower)
203        $b = pdl "[1 2 3; 4 5 6]";           # Ditto
204        $b = pdl q[1 2 3; 4 5 6];            # Ditto, using the q quote operator
205        $b = pdl "1 2 3; 4 5 6";             # Ditto, less obvious, but still works
206        $b = pdl 42                          # 0-dimensional scalar
207        $c = pdl $a;                         # Make a new copy
208
209        $u = pdl ushort(), 42                # 0-dimensional ushort scalar
210        $b = pdl(byte(),[[1,2,3],[4,5,6]]);  # 2D byte piddle
211
212        $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
216        $a = pdl([1,2,3],[4,5,6]);           # 2D
217        $a = pdl([1,2,3],[4,5,6]);           # 2D
218
219       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
223       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
229       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
233       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
238        $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
243       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
248       Throwing a PDL into the mix has the same effect as throwing in a list
249       ref:
250
251         pdl(pdl(1,2),[3,4])
252
253       is the same as
254
255         pdl([1,2],[3,4]).
256
257       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
260         $a = pdl([[1,2,3],[2]])
261
262       gives you the same answer as
263
264         $a = pdl([[1,2,3],[2,undef,undef]]);
265
266       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
270       "pdl()" is a functional synonym for the 'new' constructor, e.g.:
271
272        $x = new PDL [1..10];
273
274       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
277        $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
286       $PDL::undefval defaults to zero.
287
288       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
295   null
296       Returns a 'null' piddle.
297
298        $x = null;
299
300       "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
304        pdl> sumover sequence(10,10), $ans=null;p $ans
305        [45 145 245 345 445 545 645 745 845 945]
306
307   nullcreate
308       Returns a 'null' piddle.
309
310        $x = PDL->nullcreate($arg)
311
312       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
317       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
321        PDL::Derived->nullcreate(10)
322          returns PDL::Derived->null.
323        PDL->nullcreate($pdlderived)
324          returns $pdlderived->null.
325
326   nelem
327       Return the number of elements in a piddle
328
329        $n = nelem($piddle); $n = $piddle->nelem;
330
331        $mean = sum($data)/nelem($data);
332
333   dims
334       Return piddle dimensions as a perl list
335
336        @dims = $piddle->dims;  @dims = dims($piddle);
337
338        pdl> p @tmp = dims zeroes 10,3,22
339        10 3 22
340
341       See also shape which returns a piddle instead.
342
343   shape
344       Return piddle dimensions as a piddle
345
346        $shape = $piddle->shape;  $shape = shape($piddle);
347
348        pdl> p $shape = shape zeroes 10,3,22
349        [10 3 22]
350
351       See also dims which returns a perl list.
352
353   ndims
354       Returns the number of dimensions in a piddle. Alias for getndims.
355
356   getndims
357       Returns the number of dimensions in a piddle
358
359        $ndims = $piddle->getndims;
360
361        pdl> p zeroes(10,3,22)->getndims
362        3
363
364   dim
365       Returns the size of the given dimension of a piddle. Alias for getdim.
366
367   getdim
368       Returns the size of the given dimension.
369
370        $dim0 = $piddle->getdim(0);
371
372        pdl> p zeroes(10,3,22)->getdim(1)
373        3
374
375       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
382         print $a->getdim(10000);
383
384       will print 1 for most practically encountered piddles.
385
386   topdl
387       alternate piddle constructor - ensures arg is a piddle
388
389        $a = topdl(SCALAR|ARRAY REFERENCE|ARRAY);
390
391       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
395       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
400       Note that "topdl()" is not exported by default (see example below for
401       usage).
402
403        use PDL::Core ':Internal'; # use the internal routines of
404                                   # the Core module
405
406        $a = topdl 43;             # $a is piddle with value '43'
407        $b = topdl $piddle;        # fall through
408        $a = topdl (1,2,3,4);      # Convert 1D array
409
410   get_datatype
411       Internal: Return the numeric value identifying the piddle datatype
412
413        $x = $piddle->get_datatype;
414
415       Mainly used for internal routines.
416
417       NOTE: get_datatype returns 'just a number' not any special type object,
418       unlike type.
419
420   howbig
421       Returns the sizeof a piddle datatype in bytes.
422
423       Note that "howbig()" is not exported by default (see example below for
424       usage).
425
426        use PDL::Core ':Internal'; # use the internal routines of
427                                   # the Core module
428
429        $size = howbig($piddle->get_datatype);
430
431       Mainly used for internal routines.
432
433       NOTE: NOT a method! This is because get_datatype returns 'just a
434       number' not any special object.
435
436        pdl> p howbig(ushort([1..10])->get_datatype)
437        2
438
439   get_dataref
440       Return the internal data for a piddle, as a perl SCALAR ref.
441
442       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 new
447       location of the underlying perl variable.
448
449       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
454       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
459   upd_data
460       Update the data pointer in a piddle to match its perl SV.
461
462       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
466   threadids
467       Returns the piddle thread IDs as a perl list
468
469       Note that "threadids()" is not exported by default (see example below
470       for usage).
471
472        use PDL::Core ':Internal'; # use the internal routines of
473                                   # the Core module
474
475        @ids = threadids $piddle;
476
477   doflow
478       Turn on/off dataflow
479
480        $x->doflow;  doflow($x);
481
482   flows
483       Whether or not a piddle is indulging in dataflow
484
485        something if $x->flows; $hmm = flows($x);
486
487   new
488       new piddle constructor method
489
490        $x = PDL->new(SCALAR|ARRAY|ARRAY REF|STRING);
491
492        $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
500       Constructs piddle from perl numbers and lists and strings with
501       Matlab/Octave style constructor syntax.
502
503       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
509   copy
510       Make a physical copy of a piddle
511
512        $new = $old->copy;
513
514       Since "$new = $old" just makes a new reference, the "copy" method is
515       provided to allow real independent copies to be made.
516
517   hdr_copy
518       Return an explicit copy of the header of a PDL.
519
520       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
525       General-purpose deep copies are expensive in perl, so some simple
526       optimization happens:
527
528       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
533       This routine seems to leak memory.
534
535   unwind
536       Return a piddle which is the same as the argument except that all
537       threadids have been removed.
538
539        $y = $x->unwind;
540
541   make_physical
542       Make sure the data portion of a piddle can be accessed from XS code.
543
544        $a->make_physical;
545        $a->call_my_xs_method;
546
547       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
554       Note: this function should not be used unless absolutely necessary
555       since otherwise memory requirements might be severly increased. Instead
556       of writing your own XS code with the need to call "make_physical" you
557       might want to consider using the PDL preprocessor (see PDL::PP) which
558       can be used to transparently access virtual piddles without the need to
559       physicalise them (though there are exceptions).
560
561   dummy
562       Insert a 'dummy dimension' of given length (defaults to 1)
563
564       No relation to the 'Dungeon Dimensions' in Discworld!
565
566       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
570       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       $a->dummy(5000,1) because $a will get 5,000 dimensions, each of rank 1.
575
576       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
581        $y = $x->dummy($position[,$dimsize]);
582
583        pdl> p sequence(3)->dummy(0,3)
584        [
585         [0 0 0]
586         [1 1 1]
587         [2 2 2]
588        ]
589
590        pdl> p sequence(3)->dummy(3,2)
591        [
592         [
593          [0 1 2]
594         ]
595         [
596          [0 1 2]
597         ]
598        ]
599
600        pdl> p sequence(3)->dummy(-3,2)
601        Runtime error: PDL: For safety, <pos> < -(dims+1) forbidden in dummy.  min=-2, pos=-3
602
603   clump
604       "clumps" several dimensions into one large dimension
605
606       If called with one argument $n clumps the first $n dimensions into one.
607       For example, if $a has dimensions "(5,3,4)" then after
608
609        $b = $a->clump(2);   # Clump 2 first dimensions
610
611       the variable $b will have dimensions "(15,4)" and the element
612       "$b->at(7,3)" refers to the element "$a->at(1,2,3)".
613
614       Use "clump(-1)" to flatten a piddle. The method flat is provided as a
615       convenient alias.
616
617       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
621       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
628         $a = sequence 2,3,3,3,5; # 5D piddle
629         $c = $a->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
633   thread_define
634       define functions that support threading at the perl level
635
636        thread_define 'tline(a(n);b(n))', over {
637         line $_[0], $_[1]; # make line compliant with threading
638        };
639
640       "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
646       "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
656       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
661       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
668        PDL::thread_define 'triangles(inda();indb();indc()), NOtherPars => 2',
669         PDL::over {
670           ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
671         };
672
673       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
679        $txt = '';
680        triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
681        print $txt;
682
683       resulting in the following output
684
685        1,1,0,-1,
686        2,1,0,-1,
687        3,1,0,-1,
688
689       which is used in PDL::Graphics::TriD::VRML to generate VRML output.
690
691       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
694       Check PDL::PP for the format of the signature. Currently, the "[t]"
695       qualifier and all type qualifiers are ignored.
696
697   thread
698       Use explicit threading over specified dimensions (see also
699       PDL::Indexing)
700
701        $b = $a->thread($dim,[$dim1,...])
702
703        $a = zeroes 3,4,5;
704        $b = $a->thread(2,0);
705
706       Same as PDL::thread1, i.e. uses thread id 1.
707
708   diagonal
709       Returns the multidimensional diagonal over the specified dimensions.
710
711        $d = $x->diagonal(dim1, dim2,...)
712
713        pdl> $a = zeroes(3,3,3);
714        pdl> ($b = $a->diagonal(0,1))++;
715        pdl> p $a
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
734   thread1
735       Explicit threading over specified dims using thread id 1.
736
737        $xx = $x->thread1(3,1)
738
739        Wibble
740
741       Convenience function interfacing to PDL::Slices::threadI.
742
743   thread2
744       Explicit threading over specified dims using thread id 2.
745
746        $xx = $x->thread2(3,1)
747
748        Wibble
749
750       Convenience function interfacing to PDL::Slices::threadI.
751
752   thread3
753       Explicit threading over specified dims using thread id 3.
754
755        $xx = $x->thread3(3,1)
756
757        Wibble
758
759       Convenience function interfacing to PDL::Slices::threadI.
760
761   sever
762       sever any links of this piddle to parent piddles
763
764       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
770       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
776          $a = $pdl->index(pdl(0,3,7))->sever;
777          $a++;       # important: $pdl is not modified!
778
779       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
785          $a = zeroes(20);
786          $a->sever;   # NOOP since $a is already its own boss!
787
788       Again note: "sever" is not the same as copy!  For example,
789
790          $a = zeroes(1); # $a does not have a parent, i.e. it is not a slice etc
791          $b = $a->sever; # $b is now pointing to the same piddle as $a
792          $b++;
793          print $a;
794        [1]
795
796       but
797
798          $a = zeroes(1);
799          $b = $a->copy; # $b is now pointing to a new piddle
800          $b++;
801          print $a;
802        [0]
803
804   info
805       Return formatted information about a piddle.
806
807        $x->info($format_string);
808
809        print $x->info("Type: %T Dim: %-15D State: %S");
810
811       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
816       T      Type
817
818       D      Formatted Dimensions
819
820       F      Dataflow status
821
822       S      Some internal flags (P=physical,V=Vaffine,C=changed,B=may
823              contain bad data)
824
825       C      Class of this piddle, i.e. "ref $pdl"
826
827       A      Address of the piddle struct as a unique identifier
828
829       M      Calculated memory consumption of this piddle's data area
830
831   approx
832       test for approximately equal values (relaxed "==")
833
834         # ok if all corresponding values in
835         # piddles are within 1e-8 of each other
836         print "ok\n" if all approx $a, $b, 1e-8;
837
838       "approx" is a relaxed form of the "==" operator and often more
839       appropriate for floating point types ("float" and "double").
840
841       Usage:
842
843         $res = approx $a, $b [, $eps]
844
845       The optional parameter $eps is remembered across invocations and
846       initially set to 1e-6, e.g.
847
848         approx $a, $b;         # last $eps used (1e-6 initially)
849         approx $a, $b, 1e-10;  # 1e-10
850         approx $a, $b;         # also 1e-10
851
852   mslice
853       Convenience interface to slice, allowing easier inclusion of dimensions
854       in perl code.
855
856        $a = $x->mslice(...);
857
858        # below is the same as $x->slice("5:7,:,3:4:2")
859        $a = $x->mslice([5,7],X,[3,4,2]);
860
861   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
866       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
870        $a = $x->nslice_if_pdl(...,'(args)');
871
872   nslice
873       c<nslice> was an internally used interface for PDL::NiceSlice, but is
874       now merely a springboard to PDL::Slice.  It is deprecated and likely to
875       disappear in PDL 3.0.
876
877   inplace
878       Flag a piddle so that the next operation is done 'in place'
879
880        somefunc($x->inplace); somefunc(inplace $x);
881
882       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
889       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
894        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
899   is_inplace
900       Test the in-place flag on a piddle
901
902         $out = ($in->is_inplace) ? $in : zeroes($in);
903         $in->set_inplace(0)
904
905       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
911         $out = ($in->is_inplace(0)) ? $in : zeroes($in); # test & unset!
912
913   set_inplace
914       Set the in-place flag on a piddle
915
916         $out = ($in->is_inplace) ? $in : zeroes($in);
917         $in->set_inplace(0);
918
919       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
923   new_or_inplace
924           $a = new_or_inplace(shift());
925           $a = new_or_inplace(shift(),$preferred_type);
926
927       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
931       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
936       Note that if the inplace flag is set, no coersion happens even if you
937       specify a preferred type.
938
939   new_from_specification
940       Internal method: create piddle by specification
941
942       This is the argument processing method called by zeroes and some other
943       functions which constructs piddles from argument lists of the form:
944
945        [type], $nx, $ny, $nz,...
946
947       For $nx, $ny, etc. 0 and 1D piddles are allowed.  Giving those has the
948       same effect as if saying "$arg->list", e.g.
949
950          1, pdl(5,2), 4
951
952       is equivalent to
953
954          1, 5, 2, 4
955
956       Note, however, that in all functions using "new_from_specification"
957       calling "func $piddle" will probably not do what you want. So to play
958       safe use (e.g. with zeroes)
959
960         $pdl = zeroes $dimpdl->list;
961
962       Calling
963
964         $pdl = zeroes $dimpdl;
965
966       will rather be equivalent to
967
968         $pdl = zeroes $dimpdl->dims;
969
970       However,
971
972         $pdl = zeroes ushort, $dimpdl;
973
974       will again do what you intended since it is interpreted as if you had
975       said
976
977         $pdl = zeroes ushort, $dimpdl->list;
978
979       This is unfortunate and confusing but no good solution seems obvious
980       that would not break existing scripts.
981
982   isnull
983       Test whether a piddle is null
984
985        croak("Input piddle mustn't be null!")
986            if $input_piddle->isnull;
987
988       This function returns 1 if the piddle is null, zero if it is not. The
989       purpose of null piddles is to "tell" any PDL::PP methods to allocate
990       new memory for an output piddle, but only when that PDL::PP method is
991       called in full-arg form. Of course, there's no reason you couldn't
992       commandeer the special value for your own purposes, for which this test
993       function would prove most helpful.  But in general, you shouldn't need
994       to test for a piddle's nullness.
995
996       See "Null PDLs" for more information.
997
998   isempty
999       Test whether a piddle is empty
1000
1001        print "The piddle has zero dimension\n" if $pdl->isempty;
1002
1003       This function returns 1 if the piddle has zero elements. This is useful
1004       in particular when using the indexing function which. In the case of no
1005       match to a specified criterion, the returned piddle has zero dimension.
1006
1007        pdl> $a=sequence(10)
1008        pdl> $i=which($a < -1)
1009        pdl> print "I found no matches!\n" if ($i->isempty);
1010        I found no matches!
1011
1012       Note that having zero elements is rather different from the concept of
1013       being a null piddle, see the PDL::FAQ and PDL::Indexing manpages for
1014       discussions of this.
1015
1016   zeroes
1017       construct a zero filled piddle from dimension list or template piddle.
1018
1019       Various forms of usage,
1020
1021       (i) by specification or (ii) by template piddle:
1022
1023        # usage type (i):
1024        $a = zeroes([type], $nx, $ny, $nz,...);
1025        $a = PDL->zeroes([type], $nx, $ny, $nz,...);
1026        $a = $pdl->zeroes([type], $nx, $ny, $nz,...);
1027        # usage type (ii):
1028        $a = zeroes $b;
1029        $a = $b->zeroes
1030        zeroes inplace $a;     # Equivalent to   $a .= 0;
1031        $a->inplace->zeroes;   #  ""
1032
1033        pdl> $z = zeroes 4,3
1034        pdl> p $z
1035        [
1036         [0 0 0 0]
1037         [0 0 0 0]
1038         [0 0 0 0]
1039        ]
1040        pdl> $z = zeroes ushort, 3,2 # Create ushort array
1041        [ushort() etc. with no arg returns a PDL::Types token]
1042
1043       See also new_from_specification for details on using piddles in the
1044       dimensions list.
1045
1046   zeros
1047       construct a zero filled piddle (see zeroes for usage)
1048
1049   ones
1050       construct a one filled piddle
1051
1052        $a = ones([type], $nx, $ny, $nz,...);
1053        etc. (see 'zeroes')
1054
1055        see zeroes() and add one
1056
1057       See also new_from_specification for details on using piddles in the
1058       dimensions list.
1059
1060   reshape
1061       Change the shape (i.e. dimensions) of a piddle, preserving contents.
1062
1063        $x->reshape(NEWDIMS); reshape($x, NEWDIMS);
1064
1065       The data elements are preserved, obviously they will wrap differently
1066       and get truncated if the new array is shorter.  If the new array is
1067       longer it will be zero-padded.
1068
1069       ***Potential incompatibility with earlier versions of PDL**** If the
1070       list of "NEWDIMS" is empty "reshape" will just drop all dimensions of
1071       size 1 (preserving the number of elements):
1072
1073         $a = sequence(3,4,5);
1074         $b = $a(1,3);
1075         $b->reshape();
1076         print $b->info;
1077        PDL: Double D [5]
1078
1079       Dimensions of size 1 will also be dropped if "reshape" is invoked with
1080       the argument -1:
1081
1082         $b = $a->reshape(-1);
1083
1084       As opposed to "reshape" without arguments, "reshape(-1)" preserves
1085       dataflow:
1086
1087         $a = ones(2,1,2);
1088         $b = $a(0)->reshape(-1);
1089         $b++;
1090         print $a;
1091        [
1092         [
1093          [2 1]
1094         ]
1095         [
1096          [2 1]
1097         ]
1098        ]
1099
1100       Important: Piddles are changed inplace!
1101
1102       Note: If $x is connected to any other PDL (e.g. if it is a slice) then
1103       the connection is first severed.
1104
1105        pdl> $x = sequence(10)
1106        pdl> reshape $x,3,4; p $x
1107        [
1108         [0 1 2]
1109         [3 4 5]
1110         [6 7 8]
1111         [9 0 0]
1112        ]
1113        pdl> reshape $x,5; p $x
1114        [0 1 2 3 4]
1115
1116   squeeze
1117       eliminate all singleton dimensions (dims of size 1)
1118
1119        $b = $a(0,0)->squeeze;
1120
1121       Alias for "reshape(-1)". Removes all singleton dimensions and preserves
1122       dataflow. A more concise interface is provided by PDL::NiceSlice via
1123       modifiers:
1124
1125        use PDL::NiceSlice;
1126        $b = $a(0,0;-); # same as $a(0,0)->squeeze
1127
1128   flat
1129       flatten a piddle (alias for "$pdl->clump(-1)")
1130
1131         $srt = $pdl->flat->qsort;
1132
1133       Useful method to make a 1D piddle from an arbitrarily sized input
1134       piddle. Data flows back and forth as usual with slicing routines.
1135       Falls through if argument already <= 1D.
1136
1137   convert
1138       Generic datatype conversion function
1139
1140        $y = convert($x, $newtypenum);
1141
1142        $y = convert $x, long
1143        $y = convert $x, ushort
1144
1145       $newtype is a type number, for convenience they are returned by
1146       "long()" etc when called without arguments.
1147
1148   Datatype_conversions
1149       byte|short|ushort|long|indx|longlong|float|double (shorthands to
1150       convert datatypes)
1151
1152        $y = double $x; $y = ushort [1..10];
1153        # all of the above listed shorthands behave similarly
1154
1155       When called with a piddle argument, they convert to the specific
1156       datatype.
1157
1158       When called with a numeric, list, listref, or string argument they
1159       construct a new piddle. This is a convenience to avoid having to be
1160       long-winded and say "$x = long(pdl(42))"
1161
1162       Thus one can say:
1163
1164        $a = float(1,2,3,4);           # 1D
1165        $a = float q[1 2 3; 4 5 6];    # 2D
1166        $a = float([1,2,3],[4,5,6]);   # 2D
1167        $a = float([[1,2,3],[4,5,6]]); # 2D
1168
1169       Note the last three give identical results, and the last two are
1170       exactly equivalent - a list is automatically converted to a list
1171       reference for syntactic convenience. i.e. you can omit the outer "[]"
1172
1173       When called with no arguments, these functions return a special type
1174       token.  This allows syntactical sugar like:
1175
1176        $x = ones byte, 1000,1000;
1177
1178       This example creates a large piddle directly as byte datatype in order
1179       to save memory.
1180
1181       In order to control how undefs are handled in converting from perl
1182       lists to PDLs, one can set the variable $PDL::undefval; see the
1183       function pdl() for more details.
1184
1185        pdl> p $x=sqrt float [1..10]
1186        [1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228]
1187        pdl> p byte $x
1188        [1 1 1 2 2 2 2 2 3 3]
1189
1190   byte
1191       Convert to byte datatype
1192
1193   short
1194       Convert to short datatype
1195
1196   ushort
1197       Convert to ushort datatype
1198
1199   long
1200       Convert to long datatype
1201
1202   indx
1203       Convert to indx datatype
1204
1205   longlong
1206       Convert to longlong datatype
1207
1208   float
1209       Convert to float datatype
1210
1211   double
1212       Convert to double datatype
1213
1214   type
1215       return the type of a piddle as a blessed type object
1216
1217       A convenience function for use with the piddle constructors, e.g.
1218
1219        $b = PDL->zeroes($a->type,$a->dims,3);
1220        die "must be float" unless $a->type == float;
1221
1222       See also the discussion of the "PDL::Type" class in PDL::Types.  Note
1223       that the "PDL::Type" objects have overloaded comparison and stringify
1224       operators so that you can compare and print types:
1225
1226        $a = $a->float if $a->type < float;
1227        $t = $a->type; print "Type is $t\";
1228
1229   list
1230       Convert piddle to perl list
1231
1232        @tmp = list $x;
1233
1234       Obviously this is grossly inefficient for the large datasets PDL is
1235       designed to handle. This was provided as a get out while PDL matured.
1236       It  should now be mostly superseded by superior constructs, such as
1237       PP/threading. However it is still occasionally useful and is provied
1238       for backwards compatibility.
1239
1240        for (list $x) {
1241          # Do something on each value...
1242        }
1243
1244       If you compile PDL with bad value support (the default), your machine's
1245       docs will also say this:
1246
1247       list converts any bad values into the string 'BAD'.
1248
1249   unpdl
1250       Convert piddle to nested Perl array references
1251
1252        $arrayref = unpdl $x;
1253
1254       This function returns a reference to a Perl list-of-lists structure
1255       equivalent to the input piddle (within the limitation that while values
1256       of elements should be preserved, the detailed datatypes will not as
1257       perl itself basically has "number" data rather than byte, short, int...
1258       E.g., "sum($x - pdl( $x->unpdl ))" should equal 0.
1259
1260       Obviously this is grossly inefficient in memory and processing for the
1261       large datasets PDL is designed to handle. Sometimes, however, you
1262       really want to move your data back to Perl, and with proper
1263       dimensionality, unlike "list".
1264
1265        use JSON;
1266        my $json = encode_json unpdl $pdl;
1267
1268       If you compile PDL with bad value support (the default), your machine's
1269       docs will also say this:
1270
1271       unpdl converts any bad values into the string 'BAD'.
1272
1273   listindices
1274       Convert piddle indices to perl list
1275
1276        @tmp = listindices $x;
1277
1278       @tmp now contains the values "0..nelem($x)".
1279
1280       Obviously this is grossly inefficient for the large datasets PDL is
1281       designed to handle. This was provided as a get out while PDL matured.
1282       It  should now be mostly superseded by superior constructs, such as
1283       PP/threading. However it is still occasionally useful and is provied
1284       for backwards compatibility.
1285
1286        for $i (listindices $x) {
1287          # Do something on each value...
1288        }
1289
1290   set
1291       Set a single value inside a piddle
1292
1293        set $piddle, @position, $value
1294
1295       @position is a coordinate list, of size equal to the number of
1296       dimensions in the piddle. Occasionally useful, mainly provided for
1297       backwards compatibility as superseded by use of slice and assignment
1298       operator ".=".
1299
1300        pdl> $x = sequence 3,4
1301        pdl> set $x, 2,1,99
1302        pdl> p $x
1303        [
1304         [ 0  1  2]
1305         [ 3  4 99]
1306         [ 6  7  8]
1307         [ 9 10 11]
1308        ]
1309
1310   at
1311       Returns a single value inside a piddle as perl scalar.
1312
1313        $z = at($piddle, @position); $z=$piddle->at(@position);
1314
1315       @position is a coordinate list, of size equal to the number of
1316       dimensions in the piddle. Occasionally useful in a general context,
1317       quite useful too inside PDL internals.
1318
1319        pdl> $x = sequence 3,4
1320        pdl> p $x->at(1,2)
1321        7
1322
1323       If you compile PDL with bad value support (the default), your machine's
1324       docs will also say this:
1325
1326       at converts any bad values into the string 'BAD'.
1327
1328   sclr
1329       return a single value from a piddle as a scalar
1330
1331         $val = $a(10)->sclr;
1332         $val = sclr inner($a,$b);
1333
1334       The "sclr" method is useful to turn a piddle into a normal Perl scalar.
1335       Its main advantage over using "at" for this purpose is the fact that
1336       you do not need to worry if the piddle is 0D, 1D or higher dimensional.
1337       Using "at" you have to supply the correct number of zeroes, e.g.
1338
1339         $a = sequence(10);
1340         $b = $a->slice('4');
1341         print $b->sclr; # no problem
1342         print $b->at(); # error: needs at least one zero
1343
1344       "sclr" is generally used when a Perl scalar is required instead of a
1345       one-element piddle. If the input is a multielement piddle the first
1346       value is returned as a Perl scalar. You can optionally switch on checks
1347       to ensure that the input piddle has only one element:
1348
1349         PDL->sclr({Check => 'warn'}); # carp if called with multi-el pdls
1350         PDL->sclr({Check => 'barf'}); # croak if called with multi-el pdls
1351
1352       are the commands to switch on warnings or raise an error if a
1353       multielement piddle is passed as input. Note that these options can
1354       only be set when "sclr" is called as a class method (see example
1355       above). Use
1356
1357         PDL->sclr({Check=>0});
1358
1359       to switch these checks off again (default setting); When called as a
1360       class method the resulting check mode is returned (0: no checking, 1:
1361       warn, 2: barf).
1362
1363   cat
1364       concatenate piddles to N+1 dimensional piddle
1365
1366       Takes a list of N piddles of same shape as argument, returns a single
1367       piddle of dimension N+1.
1368
1369        pdl> $x = cat ones(3,3),zeroes(3,3),rvals(3,3); p $x
1370        [
1371         [
1372          [1 1 1]
1373          [1 1 1]
1374          [1 1 1]
1375         ]
1376         [
1377          [0 0 0]
1378          [0 0 0]
1379          [0 0 0]
1380         ]
1381         [
1382          [1 1 1]
1383          [1 0 1]
1384          [1 1 1]
1385         ]
1386        ]
1387
1388       If you compile PDL with bad value support (the default), your machine's
1389       docs will also say this:
1390
1391       The output piddle is set bad if any input piddles have their bad flag
1392       set.
1393
1394       Similar functions include append, which appends only two piddles along
1395       their first dimension, and glue, which can append more than two piddles
1396       along an arbitary dimension.
1397
1398       Also consider the generic constructor pdl, which can handle piddles of
1399       different sizes (with zero-padding), and will return a piddle of type
1400       'double' by default, but may be considerably faster (up to 10x) than
1401       cat.
1402
1403   dog
1404       Opposite of 'cat' :). Split N dim piddle to list of N-1 dim piddles
1405
1406       Takes a single N-dimensional piddle and splits it into a list of N-1
1407       dimensional piddles. The breakup is done along the last dimension.
1408       Note the dataflown connection is still preserved by default, e.g.:
1409
1410        pdl> $p = ones 3,3,3
1411        pdl> ($a,$b,$c) = dog $p
1412        pdl> $b++; p $p
1413        [
1414         [
1415          [1 1 1]
1416          [1 1 1]
1417          [1 1 1]
1418         ]
1419         [
1420          [2 2 2]
1421          [2 2 2]
1422          [2 2 2]
1423         ]
1424         [
1425          [1 1 1]
1426          [1 1 1]
1427          [1 1 1]
1428         ]
1429        ]
1430
1431        Break => 1   Break dataflow connection (new copy)
1432
1433       If you compile PDL with bad value support (the default), your machine's
1434       docs will also say this:
1435
1436       The output piddles are set bad if the original piddle has its bad flag
1437       set.
1438
1439   gethdr
1440       Retrieve header information from a piddle
1441
1442        $pdl=rfits('file.fits');
1443        $h=$pdl->gethdr;
1444        print "Number of pixels in the X-direction=$$h{NAXIS1}\n";
1445
1446       The "gethdr" function retrieves whatever header information is
1447       contained within a piddle. The header can be set with sethdr and is
1448       always a hash reference or undef.
1449
1450       "gethdr" returns undef if the piddle has not yet had a header defined;
1451       compare with "hdr" and "fhdr", which are guaranteed to return a defined
1452       value.
1453
1454       Note that gethdr() works by reference: you can modify the header in-
1455       place once it has been retrieved:
1456
1457         $a  = rfits($filename);
1458         $ah = $a->gethdr();
1459         $ah->{FILENAME} = $filename;
1460
1461       It is also important to realise that in most cases the header is not
1462       automatically copied when you copy the piddle.  See hdrcpy to enable
1463       automatic header copying.
1464
1465       Here's another example: a wrapper around rcols that allows your piddle
1466       to remember the file it was read from and the columns could be easily
1467       written (here assuming that no regexp is needed, extensions are left as
1468       an exercise for the reader)
1469
1470        sub ext_rcols {
1471           my ($file, @columns)=@_;
1472           my $header={};
1473           $$header{File}=$file;
1474           $$header{Columns}=\@columns;
1475
1476           @piddles=rcols $file, @columns;
1477           foreach (@piddles) { $_->sethdr($header); }
1478           return @piddles;
1479        }
1480
1481   hdr
1482       Retrieve or set header information from a piddle
1483
1484        $pdl->hdr->{CDELT1} = 1;
1485
1486       The "hdr" function allows convenient access to the header of a piddle.
1487       Unlike "gethdr" it is guaranteed to return a defined value, so you can
1488       use it in a hash dereference as in the example.  If the header does not
1489       yet exist, it gets autogenerated as an empty hash.
1490
1491       Note that this is usually -- but not always -- What You Want.  If you
1492       want to use a tied Astro::FITS::Header hash, for example, you should
1493       either construct it yourself and use "sethdr" to put it into the
1494       piddle, or use fhdr instead.  (Note that you should be able to write
1495       out the FITS file successfully regardless of whether your PDL has a
1496       tied FITS header object or a vanilla hash).
1497
1498   fhdr
1499       Retrieve or set FITS header information from a piddle
1500
1501        $pdl->fhdr->{CDELT1} = 1;
1502
1503       The "fhdr" function allows convenient access to the header of a piddle.
1504       Unlike "gethdr" it is guaranteed to return a defined value, so you can
1505       use it in a hash dereference as in the example.  If the header does not
1506       yet exist, it gets autogenerated as a tied Astro::FITS::Header hash.
1507
1508       Astro::FITS::Header tied hashes are better at matching the behavior of
1509       FITS headers than are regular hashes.  In particular, the hash keys are
1510       CAsE INsEnSItiVE, unlike normal hash keys.  See Astro::FITS::Header for
1511       details.
1512
1513       If you do not have Astro::FITS::Header installed, you get back a normal
1514       hash instead of a tied object.
1515
1516   sethdr
1517       Set header information of a piddle
1518
1519        $pdl = zeroes(100,100);
1520        $h = {NAXIS=>2, NAXIS1=>100, NAXIS=>100, COMMENT=>"Sample FITS-style header"};
1521        # add a FILENAME field to the header
1522        $$h{FILENAME} = 'file.fits';
1523        $pdl->sethdr( $h );
1524
1525       The "sethdr" function sets the header information for a piddle.  You
1526       must feed in a hash ref or undef, and the header field of the PDL is
1527       set to be a new ref to the same hash (or undefined).
1528
1529       The hash ref requirement is a speed bump put in place since the normal
1530       use of headers is to store fits header information and the like.  Of
1531       course, if you want you can hang whatever ugly old data structure you
1532       want off of the header, but that makes life more complex.
1533
1534       Remember that the hash is not copied -- the header is made into a ref
1535       that points to the same underlying data.  To get a real copy without
1536       making any assumptions about the underlying data structure, you can use
1537       one of the following:
1538
1539         use PDL::IO::Dumper;
1540         $pdl->sethdr( deep_copy($h) );
1541
1542       (which is slow but general), or
1543
1544         $pdl->sethdr( PDL::_hdr_copy($h) )
1545
1546       (which uses the built-in sleazy deep copier), or (if you know that all
1547       the elements happen to be scalars):
1548
1549         { my %a = %$h;
1550           $pdl->sethdr(\%a);
1551         }
1552
1553       which is considerably faster but just copies the top level.
1554
1555       The "sethdr" function must be given a hash reference or undef.  For
1556       further information on the header, see gethdr, hdr, fhdr and hdrcpy.
1557
1558   hdrcpy
1559       switch on/off/examine automatic header copying
1560
1561        print "hdrs will be copied" if $a->hdrcpy;
1562        $a->hdrcpy(1);       # switch on automatic header copying
1563        $b = $a->sumover;    # and $b will inherit $a's hdr
1564        $a->hdrcpy(0);       # and now make $a non-infectious again
1565
1566       "hdrcpy" without an argument just returns the current setting of the
1567       flag.  See also "hcpy" which returns its PDL argument (and so is useful
1568       in method-call pipelines).
1569
1570       Normally, the optional header of a piddle is not copied automatically
1571       in pdl operations. Switching on the hdrcpy flag using the "hdrcpy"
1572       method will enable automatic hdr copying. Note that an actual deep copy
1573       gets made, which is rather processor-inefficient -- so avoid using
1574       header copying in tight loops!
1575
1576       Most PDLs have the "hdrcpy" flag cleared by default; however, some
1577       routines (notably rfits) set it by default where that makes more sense.
1578
1579       The "hdrcpy" flag is viral: if you set it for a PDL, then derived PDLs
1580       will get copies of the header and will also have their "hdrcpy" flags
1581       set.  For example:
1582
1583         $a = xvals(50,50);
1584         $a->hdrcpy(1);
1585         $a->hdr->{FOO} = "bar";
1586         $b = $a++;
1587         $c = $b++;
1588         print $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1589         $b->hdr->{FOO} = "baz";
1590         print $a->hdr->{FOO}, " - ", $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1591
1592       will print:
1593
1594         bar - bar
1595         bar - baz - bar
1596
1597       Performing an operation in which more than one PDL has its hdrcpy flag
1598       causes the resulting PDL to take the header of the first PDL:
1599
1600         ($a,$b) = sequence(5,2)->dog;
1601         $a->hdrcpy(1); $b->hdrcpy(1);
1602         $a->hdr->{foo} = 'a';
1603         $b->hdr->{foo} = 'b';
1604         print (($a+$b)->hdr->{foo} , ($b+$a)->hdr->{foo});
1605
1606       will print:
1607
1608         a b
1609
1610   hcpy
1611       Switch on/off automatic header copying, with PDL pass-through
1612
1613         $a = rfits('foo.fits')->hcpy(0);
1614         $a = rfits('foo.fits')->hcpy(1);
1615
1616       "hcpy" sets or clears the hdrcpy flag of a PDL, and returns the PDL
1617       itself.  That makes it convenient for inline use in expressions.
1618
1619   set_autopthread_targ
1620       Set the target number of processor threads (pthreads) for multi-
1621       threaded processing.
1622
1623        set_autopthread_targ($num_pthreads);
1624
1625       $num_pthreads is the target number of pthreads the auto-pthread process
1626       will try to achieve.
1627
1628       See PDL::ParallelCPU for an overview of the auto-pthread process.
1629
1630         # Example turning on auto-pthreading for a target of 2 pthreads and for functions involving
1631         #   PDLs with greater than 1M elements
1632         set_autopthread_targ(2);
1633         set_autopthread_size(1);
1634
1635         # Execute a pdl function, processing will split into two pthreads as long as
1636         #  one of the pdl-threaded dimensions is divisible by 2.
1637         $a = minimum($b);
1638
1639         # Get the actual number of pthreads that were run.
1640         $actual_pthread = get_autopthread_actual();
1641
1642   get_autopthread_targ
1643       Get the current target number of processor threads (pthreads) for
1644       multi-threaded processing.
1645
1646        $num_pthreads = get_autopthread_targ();
1647
1648       $num_pthreads is the target number of pthreads the auto-pthread process
1649       will try to achieve.
1650
1651       See PDL::ParallelCPU for an overview of the auto-pthread process.
1652
1653   get_autopthread_actual
1654       Get the actual number of pthreads executed for the last pdl processing
1655       function.
1656
1657        $autopthread_actual = get_autopthread_actual();
1658
1659       $autopthread_actual is the actual number of pthreads executed for the
1660       last pdl processing function.
1661
1662       See PDL::ParallelCPU for an overview of the auto-pthread process.
1663
1664   set_autopthread_size
1665       Set the minimum size (in M-elements or 2^20 elements) of the largest
1666       PDL involved in a function where auto-pthreading will be performed. For
1667       small PDLs, it probably isn't worth starting multiple pthreads, so this
1668       function is used to define a minimum threshold where auto-pthreading
1669       won't be attempted.
1670
1671        set_autopthread_size($size);
1672
1673       $size is the mimumum size, in M-elements or 2^20 elements (approx 1e6
1674       elements) for the largest PDL involved in a function.
1675
1676       See PDL::ParallelCPU for an overview of the auto-pthread process.
1677
1678         # Example turning on auto-pthreading for a target of 2 pthreads and for functions involving
1679         #   PDLs with greater than 1M elements
1680         set_autopthread_targ(2);
1681         set_autopthread_size(1);
1682
1683         # Execute a pdl function, processing will split into two pthreads as long as
1684         #  one of the pdl-threaded dimensions is divisible by 2.
1685         $a = minimum($b);
1686
1687         # Get the actual number of pthreads that were run.
1688         $actual_pthread = get_autopthread_actual();
1689
1690   get_autopthread_size
1691       Get the current autopthread_size setting.
1692
1693        $autopthread_size = get_autopthread_size();
1694
1695       $autopthread_size is the mimumum size limit for auto_pthreading to
1696       occur, in M-elements or 2^20 elements (approx 1e6 elements) for the
1697       largest PDL involved in a function
1698
1699       See PDL::ParallelCPU for an overview of the auto-pthread process.
1700

AUTHOR

1702       Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka,
1703       (lukka@husc.harvard.edu) and Christian Soeller
1704       (c.soeller@auckland.ac.nz) 1997.  Modified, Craig DeForest
1705       (deforest@boulder.swri.edu) 2002.  All rights reserved. There is no
1706       warranty. You are allowed to redistribute this software / documentation
1707       under certain conditions. For details, see the file COPYING in the PDL
1708       distribution. If this file is separated from the PDL distribution, the
1709       copyright notice should be included in the file.
1710
1711
1712
1713perl v5.28.0                      2018-05-05                           Core(3)
Impressum