Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Core(3)		      User Contributed Perl Documentation	       Core(3)

NAME
       PDL::Core - fundamental PDL functionality and vectorization/threading

DESCRIPTION
       Methods and functions for type conversions, PDL creation, type
       conversion, threading etc.

SYNOPSIS
	use PDL::Core;		   # Normal routines
	use PDL::Core ':Internal'; # Hairy routines

VECTORIZATION/THREADING: METHOD	AND NOMENCLATURE
       PDL provides vectorized operations via a	built-in engine.
       Vectorization is	called "threading" for historical reasons.  The
       threading engine	implements simple rules	for each operation.

       Each PDL	object has a "shape" that is a generalized N-dimensional
       rectangle defined by a "dim list" of sizes in an	arbitrary set of
       dimensions.  A PDL with shape 2x3 has 6 elements	and is said to be two-
       dimensional, or may be referred to as a 2x3-PDL.	 The dimensions	are
       indexed numerically starting at 0, so a 2x3-PDL has a dimension 0 (or
       "dim 0")	with size 2 and	a 1 dimension (or "dim 1") with	size 3.

       PDL generalizes *all* mathematical operations with the notion of
       "active dims": each operator has	zero or	more active dims that are used
       in carrying out the operation.  Simple scalar operations	like scalar
       multiplication ('*') have 0 active dims.	 More complicated operators
       can have	more active dims.  For example,	matrix multiplication ('x')
       has 2 active dims.  Additional dims are automatically vectorized	across
       -- e.g. multiplying a 2x5-PDL with a 2x5-PDL requires 10	simple
       multiplication operations, and yields a 2x5-PDL result.

   Threading rules
       In any PDL expression, the active dims appropriate for each operator
       are used	starting at the	0 dim and working forward through the dim list
       of each object.	All additional dims after the active dims are "thread
       dims".  The thread dims do not have to agree exactly: they are coerced
       to agree	according to simple rules:

       o  Null PDLs match any dim list (see below).

       o  Dims with sizes other	than 1 must all	agree in size.

       o  Dims of size 1 are expanded as necessary.

       o  Missing dims are expanded appropriately.

       The "size 1" rule implements "generalized scalar" operation, by analogy
       to scalar multiplication.  The "missing dims" rule acknowledges the
       ambiguity between a missing dim and a dim of size 1.

   Null	PDLs
       PDLs on the left-hand side of assignment	can have the special value
       "Null".	A null PDL has no dim list and no set size; its	shape is
       determined by the computed shape	of the expression being	assigned to
       it.   Null PDLs contain no values and can only be assigned to.  When
       assigned	to (e.g. via the ".=" operator), they cease to be null PDLs.

       To create a null	PDL, use "PDL->null()".

   Empty PDLs
       PDLs can	represent the empty set	using "structured Empty" variables.
       An empty	PDL is not a null PDL.

       Any dim of a PDL	can be set explicitly to size 0.  If so, the PDL
       contains	zero values (because the total number of values	is the product
       of all the sizes	in the PDL's shape or dimlist).

       Scalar PDLs are zero-dimensional	and have no entries in the dim list,
       so they cannot be empty.	 1-D and higher	PDLs can be empty.  Empty PDLs
       are useful for set operations, and are most commonly encountered	in the
       output from selection operators such as which and whichND.  Not all
       empty PDLs have the same	threading properties --	e.g. a 2x0-PDL
       represents a collection of 2-vectors that happens to contain no
       elements, while a simple	0-PDL represents a collection of scalar	values
       (that also happens to contain no	elements).

       Note that 0 dims	are not	adjustable via the threading rules -- a	dim
       with size 0 can only match a corresponding dim of size 0	or 1.

   Thread rules	and assignments
       Versions	of PDL through 2.4.10 have some	irregularity with threading
       and assignments.	 Currently the threading engine	performs a full
       expansion of both sides of the computed assignment operator ".="	(which
       assigns values to a pre-existing	PDL).  This leads to counter-intuitive
       behavior	in some	cases:

       o  Generalized scalars and computed assignment

	  If the PDL on	the left-hand side of ".=" has a dim of	size 1,	it can
	  be treated as	a generalized scalar, as in:

	      $a = sequence(2,3);
	      $b = zeroes(1,3);
	      $b .= $a;

	  In this case,	$b is automatically treated as a 2x3-PDL during	the
	  threading operation, but half	of the values from $a silently
	  disappear.  The output is, as	Kernighan and Ritchie would say,
	  "undefined".

	  Further, if the value	on the right of	".=" is	empty, then ".="
	  becomes a silent no-op:

	      $a = zeroes(0);
	      $b = zeroes(1);
	      $b .= $a+1;
	      print $b;

	  will print "[0]".  In	this case, "$a+1" is empty, and	"$b" is	a
	  generalized scalar that is adjusted to be empty, so the assignment
	  is carried out for zero elements (a no-op).

	  Both of these	behaviors are considered harmful and should not	be
	  relied upon: they may	be patched away	in a future version of PDL.

       o  Empty	PDLs and generalized scalars

	  Generalized scalars (PDLs with a dim of size 1) can match any	size
	  in the corresponding dim, including 0.  Thus,

	      $a = ones(2,0);
	      $b = sequence(2,1);
	      $c = $a *	$b;
	      print $c;

	  prints "Empty[2,0]".

	  This behavior	is counterintuitive but	desirable, and will be
	  preserved in future versions of PDL.

VARIABLES
       These are important variables of	global scope and are placed in the PDL
       namespace.

       $PDL::debug

	   When	true, PDL debugging information	is printed.

       $PDL::verbose

	   When	true, PDL functions provide chatty information.

       $PDL::use_commas

	   Whether to insert commas when printing pdls

       $PDL::floatformat, $PDL::doubleformat, $PDL::indxformat

	   The default print format for	floats,	doubles, and indx values,
	   respectively.  The default default values are:

	     $PDL::floatformat	= "%7g";
	     $PDL::doubleformat	= "%10.8g";
	     $PDL::indxformat	= "%12d";

       $PDL::undefval

	   The value to	use instead of "undef" when creating pdls.

       $PDL::toolongtoprint

	   The maximal size pdls to print (defaults to 10000 elements)

FUNCTIONS
   barf
       Standard	error reporting	routine	for PDL.

       "barf()"	is the routine PDL modules should call to report errors. This
       is because "barf()" will	report the error as coming from	the correct
       line in the module user's script	rather than in the PDL module.

       For now,	barf just calls	Carp::confess()

       Remember	"barf()" is your friend. *Use* it!

       At the perl level:

	barf("User has too low an IQ!");

       In C or XS code:

	barf("You have made %d errors",	count);

       Note: this is one of the	few functions ALWAYS exported by PDL::Core

   pdl
       PDL constructor - creates new piddle from perl scalars/arrays, piddles,
       and strings

	$double_pdl = pdl(SCALAR|ARRAY REFERENCE|ARRAY|STRING);	 # default type
	$type_pdl   = pdl(PDL::Type,SCALAR|ARRAY REFERENCE|ARRAY|STRING);

	$a = pdl [1..10];		     # 1D array
	$a = pdl ([1..10]);		     # 1D array
	$a = pdl (1,2,3,4);		     # Ditto
	$b = pdl [[1,2,3],[4,5,6]];	     # 2D 3x2 array
	$b = pdl "[[1,2,3],[4,5,6]]";	     # Ditto (slower)
	$b = pdl "[1 2 3; 4 5 6]";	     # Ditto
	$b = pdl q[1 2 3; 4 5 6];	     # Ditto, using the	q quote	operator
	$b = pdl "1 2 3; 4 5 6";	     # Ditto, less obvious, but	still works
	$b = pdl 42			     # 0-dimensional scalar
	$c = pdl $a;			     # Make a new copy

	$u = pdl ushort(), 42		     # 0-dimensional ushort scalar
	$b = pdl(byte(),[[1,2,3],[4,5,6]]);  # 2D byte piddle

	$n = pdl indx(), [1..5];	     # 1D array	of indx	values
	$n = pdl indx, [1..5];		     # ... can leave off parens
	$n = indx( [1..5] );		     # ... still the same!

	$a = pdl([1,2,3],[4,5,6]);	     # 2D
	$a = pdl([1,2,3],[4,5,6]);	     # 2D

       Note the	last two are equivalent	- a list is automatically converted to
       a list reference	for syntactic convenience. i.e.	you can	omit the outer
       "[]"

       You can mix and match arrays, array refs, and PDLs in your argument
       list, and "pdl" will sort them out.  You	get back a PDL whose last
       (slowest	running) dim runs across the top level of the list you hand
       in, and whose first (fastest running) dim runs across the deepest level
       that you	supply.

       At the moment, you cannot mix and match those arguments with string
       arguments, though we can't imagine a situation in which you would
       really want to do that.

       The string version of pdl also allows you to use	the strings "bad",
       "inf", and "nan", and it	will insert the	values that you	mean (and set
       the bad flag if you use "bad"). You can mix and match case, though you
       shouldn't. Here are some	examples:

	$bad = pdl q[1 2 3 bad 5 6];  #	Set fourth element to the bad value
	$bad = pdl q[1 2 3 BAD 5 6];  #	ditto
	$bad = pdl q[1 2 inf bad 5];  #	now third element is IEEE infinite value
	$bad = pdl q[nan 2 inf -inf]; #	first value is IEEE nan	value

       The default constructor uses IEEE double-precision floating point
       numbers.	You can	use other types, but you will get a warning if you try
       to use "nan" with integer types (it will	be replaced with the "bad"
       value) and you will get a fatal error if	you try	to use "inf".

       Throwing	a PDL into the mix has the same	effect as throwing in a	list
       ref:

	 pdl(pdl(1,2),[3,4])

       is the same as

	 pdl([1,2],[3,4]).

       All of the dimensions in	the list are "padded-out" with undefval	to
       meet the	widest dim in the list,	so (e.g.)

	 $a = pdl([[1,2,3],[2]])

       gives you the same answer as

	 $a = pdl([[1,2,3],[2,undef,undef]]);

       If your PDL module has bad values compiled into it (see PDL::Bad), you
       can pass	BAD values into	the constructor	within pre-existing PDLs.  The
       BAD values are automatically kept BAD and propagated correctly.

       "pdl()" is a functional synonym for the 'new' constructor, e.g.:

	$x = new PDL [1..10];

       In order	to control how undefs are handled in converting	from perl
       lists to	PDLs, one can set the variable $PDL::undefval.	For example:

	$foo = [[1,2,undef],[undef,3,4]];
	$PDL::undefval = -999;
	$f = pdl $foo;
	print $f
	[
	 [   1	  2 -999]
	 [-999	  3    4]
	]

       $PDL::undefval defaults to zero.

       As a final note,	if you include an Empty	PDL in the list	of objects to
       construct into a	PDL, it	is kept	as a placeholder pane -- so if you
       feed in (say) 7 objects,	you get	a size of 7 in the 0th dim of the
       output PDL.  The	placeholder panes are completely padded	out.  But if
       you feed	in only	a single Empty PDL, you	get back the Empty PDL (no
       padding).

   null
       Returns a 'null'	piddle.

	$x = null;

       "null()"	has a special meaning to PDL::PP. It is	used to	flag a special
       kind of empty piddle, which can grow to appropriate dimensions to store
       a result	(as opposed to storing a result	in an existing piddle).

	pdl> sumover sequence(10,10), $ans=null;p $ans
	[45 145	245 345	445 545	645 745	845 945]

   nullcreate
       Returns a 'null'	piddle.

	$x = PDL->nullcreate($arg)

       This is an routine used by many of the threading	primitives (i.e.
       sumover,	minimum, etc.) to generate a null piddle for the function's
       output that will	behave properly	for derived (or	subclassed) PDL
       objects.

       For the above usage: If $arg is a PDL, or a derived PDL,	then
       "$arg->null" is returned.  If $arg is a scalar (i.e. a zero-dimensional
       PDL) then "PDL->null" is	returned.

	PDL::Derived->nullcreate(10)
	  returns PDL::Derived->null.
	PDL->nullcreate($pdlderived)
	  returns $pdlderived->null.

   nelem
       Return the number of elements in	a piddle

	$n = nelem($piddle); $n	= $piddle->nelem;

	$mean =	sum($data)/nelem($data);

   dims
       Return piddle dimensions	as a perl list

	@dims =	$piddle->dims;	@dims =	dims($piddle);

	pdl> p @tmp = dims zeroes 10,3,22
	10 3 22

       See also	shape which returns a piddle instead.

   shape
       Return piddle dimensions	as a piddle

	$shape = $piddle->shape;  $shape = shape($piddle);

	pdl> p $shape =	shape zeroes 10,3,22
	[10 3 22]

       See also	dims which returns a perl list.

   ndims
       Returns the number of dimensions	in a piddle. Alias for getndims.

   getndims
       Returns the number of dimensions	in a piddle

	$ndims = $piddle->getndims;

	pdl> p zeroes(10,3,22)->getndims
	3

   dim
       Returns the size	of the given dimension of a piddle. Alias for getdim.

   getdim
       Returns the size	of the given dimension.

	$dim0 =	$piddle->getdim(0);

	pdl> p zeroes(10,3,22)->getdim(1)
	3

       Negative	indices	count from the end of the dims array.  Indices beyond
       the end will return a size of 1.	This reflects the idea that any	pdl is
       equivalent to an	infinitely dimensional array in	which only a finite
       number of dimensions have a size	different from one. For	example, in
       that sense a 3D piddle of shape [3,5,2] is equivalent to	a
       [3,5,2,1,1,1,1,1,....]  piddle. Accordingly,

	 print $a->getdim(10000);

       will print 1 for	most practically encountered piddles.

   topdl
       alternate piddle	constructor - ensures arg is a piddle

	$a = topdl(SCALAR|ARRAY	REFERENCE|ARRAY);

       The difference between pdl() and	"topdl()" is that the latter will just
       'fall through' if the argument is already a piddle. It will return a
       reference and NOT a new copy.

       This is particularly useful if you are writing a	function which is
       doing some fiddling with	internals and assumes a	piddle argument	(e.g.
       for method calls). Using	"topdl()" will ensure nothing breaks if	passed
       with '2'.

       Note that "topdl()" is not exported by default (see example below for
       usage).

	use PDL::Core ':Internal'; # use the internal routines of
				   # the Core module

	$a = topdl 43;		   # $a	is piddle with value '43'
	$b = topdl $piddle;	   # fall through
	$a = topdl (1,2,3,4);	   # Convert 1D	array

   get_datatype
       Internal: Return	the numeric value identifying the piddle datatype

	$x = $piddle->get_datatype;

       Mainly used for internal	routines.

       NOTE: get_datatype returns 'just	a number' not any special type object,
       unlike type.

   howbig
       Returns the sizeof a piddle datatype in bytes.

       Note that "howbig()" is not exported by default (see example below for
       usage).

	use PDL::Core ':Internal'; # use the internal routines of
				   # the Core module

	$size =	howbig($piddle->get_datatype);

       Mainly used for internal	routines.

       NOTE: NOT a method! This	is because get_datatype	returns	'just a
       number' not any special object.

	pdl> p howbig(ushort([1..10])->get_datatype)
	2

   get_dataref
       Return the internal data	for a piddle, as a perl	SCALAR ref.

       Most piddles hold their internal	data in	a packed perl string, to take
       advantage of perl's memory management.  This gives you direct access to
       the string, which is handy when you need	to manipulate the binary data
       directly	(e.g. for file I/O).  If you modify the	string,	you'll need to
       call upd_data afterward,	to make	sure that the piddle points to the new
       location	of the underlying perl variable.

       Calling "get_dataref" automatically physicalizes	your piddle (see
       make_physical).	You definitely don't want to do	anything to the	SV to
       truncate	or deallocate the string, unless you correspondingly call
       reshape to make the PDL match its new data dimension.

       You definitely don't want to use	get_dataref unless you know what you
       are doing (or are trying	to find	out): you can end up scrozzling	memory
       if you shrink or	eliminate the string representation of the variable.
       Here be dragons.

   upd_data
       Update the data pointer in a piddle to match its	perl SV.

       This is useful if you've	been monkeying with the	packed string
       representation of the PDL, which	you probably shouldn't be doing
       anyway.	(see get_dataref.)

   threadids
       Returns the piddle thread IDs as	a perl list

       Note that "threadids()" is not exported by default (see example below
       for usage).

	use PDL::Core ':Internal'; # use the internal routines of
				   # the Core module

	@ids = threadids $piddle;

   doflow
       Turn on/off dataflow

	$x->doflow;  doflow($x);

   flows
       Whether or not a	piddle is indulging in dataflow

	something if $x->flows;	$hmm = flows($x);

   new
       new piddle constructor method

	$x = PDL->new(SCALAR|ARRAY|ARRAY REF|STRING);

	$x = PDL->new(42);	       # new from a Perl scalar
	$x = new PDL 42;	       # ditto
	$y = PDL->new(@list_of_vals);  # new from Perl list
	$y = new PDL @list_of_vals;    # ditto
	$z = PDL->new(\@list_of_vals); # new from Perl list reference
	$w = PDL->new("[1 2 3]");      # new from Perl string, using
				       # Matlab	constructor syntax

       Constructs piddle from perl numbers and lists and strings with
       Matlab/Octave style constructor syntax.

       The string input	is fairly versatile though not performance optimized.
       The goal	is to make it easy to copy and paste code from PDL output and
       to offer	a familiar Matlab syntax for piddle construction. As of	May,
       2010, it	is a new feature, so feel free to report bugs or suggest new
       features.  See documentation for	pdl for	more examples of usage.

   copy
       Make a physical copy of a piddle

	$new = $old->copy;

       Since "$new = $old" just	makes a	new reference, the "copy" method is
       provided	to allow real independent copies to be made.

   hdr_copy
       Return an explicit copy of the header of	a PDL.

       hdr_copy	is just	a wrapper for the internal routine _hdr_copy, which
       takes the hash ref itself.  That	is the routine which is	used to	make
       copies of the header during normal operations if	the hdrcpy() flag of a
       PDL is set.

       General-purpose deep copies are expensive in perl, so some simple
       optimization happens:

       If the header is	a tied array or	a blessed hash ref with	an associated
       method called "copy", then that ->copy method is	called.	 Otherwise,
       all elements of the hash	are explicitly copied.	References are
       recursively deep	copied.

       This routine seems to leak memory.

   unwind
       Return a	piddle which is	the same as the	argument except	that all
       threadids have been removed.

	$y = $x->unwind;

   make_physical
       Make sure the data portion of a piddle can be accessed from XS code.

	$a->make_physical;
	$a->call_my_xs_method;

       Ensures that a piddle gets its own allocated copy of data. This
       obviously implies that there are	certain	piddles	which do not have
       their own data.	These are so called virtual piddles that make use of
       the vaffine optimisation	(see PDL::Indexing).  They do not have their
       own copy	of data	but instead store only access information to some (or
       all) of another piddle's	data.

       Note: this function should not be used unless absolutely	necessary
       since otherwise memory requirements might be severly increased. Instead
       of writing your own XS code with	the need to call "make_physical" you
       might want to consider using the	PDL preprocessor (see PDL::PP) which
       can be used to transparently access virtual piddles without the need to
       physicalise them	(though	there are exceptions).

   dummy
       Insert a	'dummy dimension' of given length (defaults to 1)

       No relation to the 'Dungeon Dimensions' in Discworld!

       Negative	positions specify relative to last dimension, i.e. "dummy(-1)"
       appends one dimension at	end, "dummy(-2)" inserts a dummy dimension in
       front of	the last dim, etc.

       If you specify a	dimension position larger than the existing dimension
       list of your PDL, the PDL gets automagically padded with	extra dummy
       dimensions so that you get the dim you asked for, in the	slot you asked
       for.  This could	cause you trouble if, for example, you ask for
       $a->dummy(5000,1) because $a will get 5,000 dimensions, each of rank 1.

       Because padding at the beginning	of the dimension list moves existing
       dimensions from slot to slot, it's considered unsafe, so	automagic
       padding doesn't work for	large negative indices -- only for large
       positive	indices.

	$y = $x->dummy($position[,$dimsize]);

	pdl> p sequence(3)->dummy(0,3)
	[
	 [0 0 0]
	 [1 1 1]
	 [2 2 2]
	]

	pdl> p sequence(3)->dummy(3,2)
	[
	 [
	  [0 1 2]
	 ]
	 [
	  [0 1 2]
	 ]
	]

	pdl> p sequence(3)->dummy(-3,2)
	Runtime	error: PDL: For	safety,	<pos> <	-(dims+1) forbidden in dummy.  min=-2, pos=-3

   clump
       "clumps"	several	dimensions into	one large dimension

       If called with one argument $n clumps the first $n dimensions into one.
       For example, if $a has dimensions "(5,3,4)" then	after

	$b = $a->clump(2);   # Clump 2 first dimensions

       the variable $b will have dimensions "(15,4)" and the element
       "$b->at(7,3)" refers to the element "$a->at(1,2,3)".

       Use "clump(-1)" to flatten a piddle. The	method flat is provided	as a
       convenient alias.

       Clumping	with a negative	dimension in general leaves that many
       dimensions behind -- e.g. clump(-2) clumps all of the first few
       dimensions into a single	one, leaving a 2-D piddle.

       If "clump" is called with an index list with more than one element it
       is treated as a list of dimensions that should be clumped together into
       one. The	resulting clumped dim is placed	at the position	of the lowest
       index in	the list.  This	convention ensures that	"clump"	does the
       expected	thing in the usual cases. The following	example	demonstrates
       typical usage:

	 $a = sequence 2,3,3,3,5; # 5D piddle
	 $c = $a->clump(1..3);	  # clump all the dims 1 to 3 into one
	 print $c->info;	  # resulting 3D piddle	has clumped dim	at pos 1
	PDL: Double D [2,27,5]

   thread_define
       define functions	that support threading at the perl level

	thread_define 'tline(a(n);b(n))', over {
	 line $_[0], $_[1]; # make line	compliant with threading
	};

       "thread_define" provides	some support for threading (see	PDL::Indexing)
       at the perl level. It allows you	to do things for which you normally
       would have resorted to PDL::PP (see PDL::PP); however, it is most
       useful to wrap existing perl functions so that the new routine supports
       PDL threading.

       "thread_define" is used to define new threading aware functions.	Its
       first argument is a symbolic repesentation of the new function to be
       defined.	The string is composed of the name of the new function
       followed	by its signature (see PDL::Indexing and	PDL::PP) in
       parentheses. The	second argument	is a subroutine	that will be called
       with the	slices of the actual runtime arguments as specified by its
       signature. Correct dimension sizes and minimal number of	dimensions for
       all arguments will be checked (assuming the rules of PDL	threading, see
       PDL::Indexing).

       The actual work is done by the "signature" class	which parses the
       signature string, does runtime dimension	checks and the routine
       "threadover" that generates the loop over all appropriate slices	of pdl
       arguments and creates pdls as needed.

       Similar to "pp_def" and its "OtherPars" option it is possible to	define
       the new function	so that	it accepts normal perl args as well as
       piddles.	You do this by using the "NOtherPars" parameter	in the
       signature. The number of	"NOtherPars" specified will be passed
       unaltered into the subroutine given as the second argument of
       "thread_define".	Let's illustrate this with an example:

	PDL::thread_define 'triangles(inda();indb();indc()), NOtherPars	=> 2',
	 PDL::over {
	   ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
	 };

       This defines a function "triangles" that	takes 3	piddles	as input plus
       2 arguments which are passed into the routine unaltered.	This routine
       is used to collect lists	of indices into	a perl scalar that is passed
       by reference. Each line is preceded by a	prefix passed as $_[4].	Here
       is typical usage:

	$txt = '';
	triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
	print $txt;

       resulting in the	following output

	1,1,0,-1,
	2,1,0,-1,
	3,1,0,-1,

       which is	used in	PDL::Graphics::TriD::VRML to generate VRML output.

       Currently, this is probably not much more than a	POP (proof of
       principle) but is hoped to be useful enough for some real life work.

       Check PDL::PP for the format of the signature. Currently, the "[t]"
       qualifier and all type qualifiers are ignored.

   thread
       Use explicit threading over specified dimensions	(see also
       PDL::Indexing)

	$b = $a->thread($dim,[$dim1,...])

	$a = zeroes 3,4,5;
	$b = $a->thread(2,0);

       Same as PDL::thread1, i.e. uses thread id 1.

   diagonal
       Returns the multidimensional diagonal over the specified	dimensions.

	$d = $x->diagonal(dim1,	dim2,...)

	pdl> $a	= zeroes(3,3,3);
	pdl> ($b = $a->diagonal(0,1))++;
	pdl> p $a
	[
	 [
	  [1 0 0]
	  [0 1 0]
	  [0 0 1]
	 ]
	 [
	  [1 0 0]
	  [0 1 0]
	  [0 0 1]
	 ]
	 [
	  [1 0 0]
	  [0 1 0]
	  [0 0 1]
	 ]
	]

   thread1
       Explicit	threading over specified dims using thread id 1.

	$xx = $x->thread1(3,1)

	Wibble

       Convenience function interfacing	to PDL::Slices::threadI.

   thread2
       Explicit	threading over specified dims using thread id 2.

	$xx = $x->thread2(3,1)

	Wibble

       Convenience function interfacing	to PDL::Slices::threadI.

   thread3
       Explicit	threading over specified dims using thread id 3.

	$xx = $x->thread3(3,1)

	Wibble

       Convenience function interfacing	to PDL::Slices::threadI.

   sever
       sever any links of this piddle to parent	piddles

       In PDL it is possible for a piddle to be	just another view into another
       piddle's	data. In that case we call this	piddle a virtual piddle	and
       the original piddle owning the data its parent. In other	languages
       these alternate views sometimes run by names such as alias or smart
       reference.

       Typical functions that return such piddles are "slice", "xchg",
       "index",	etc. Sometimes,	however, you would like	to separate the
       virtual piddle from its parent's	data and just give it a	life of	its
       own (so that manipulation of its	data doesn't change the	parent).  This
       is simply achieved by using "sever". For	example,

	  $a = $pdl->index(pdl(0,3,7))->sever;
	  $a++;	      #	important: $pdl	is not modified!

       In many (but not	all) circumstances it acts therefore similar to	copy.
       However,	in general performance is better with "sever" and secondly,
       "sever" doesn't lead to futile copying when used	on piddles that
       already have their own data. On the other hand, if you really want to
       make sure to work on a copy of a	piddle use copy.

	  $a = zeroes(20);
	  $a->sever;   # NOOP since $a is already its own boss!

       Again note: "sever" is not the same as copy!  For example,

	  $a = zeroes(1); # $a does not	have a parent, i.e. it is not a	slice etc
	  $b = $a->sever; # $b is now pointing to the same piddle as $a
	  $b++;
	  print	$a;
	[1]

       but

	  $a = zeroes(1);
	  $b = $a->copy; # $b is now pointing to a new piddle
	  $b++;
	  print	$a;
	[0]

   info
       Return formatted	information about a piddle.

	$x->info($format_string);

	print $x->info("Type: %T Dim: %-15D State: %S");

       Returns a string	with info about	a piddle. Takes	an optional argument
       to specify the format of	information a la sprintf.  Format specifiers
       are in the form "%<width><letter>" where	the width is optional and the
       letter is one of

       T      Type

       D      Formatted	Dimensions

       F      Dataflow status

       S      Some internal flags (P=physical,V=Vaffine,C=changed,B=may
	      contain bad data)

       C      Class of this piddle, i.e. "ref $pdl"

       A      Address of the piddle struct as a	unique identifier

       M      Calculated memory	consumption of this piddle's data area

   approx
       test for	approximately equal values (relaxed "==")

	 # ok if all corresponding values in
	 # piddles are within 1e-8 of each other
	 print "ok\n" if all approx $a,	$b, 1e-8;

       "approx"	is a relaxed form of the "==" operator and often more
       appropriate for floating	point types ("float" and "double").

       Usage:

	 $res =	approx $a, $b [, $eps]

       The optional parameter $eps is remembered across	invocations and
       initially set to	1e-6, e.g.

	 approx	$a, $b;		# last $eps used (1e-6 initially)
	 approx	$a, $b,	1e-10;	# 1e-10
	 approx	$a, $b;		# also 1e-10

   mslice
       Convenience interface to	slice, allowing	easier inclusion of dimensions
       in perl code.

	$a = $x->mslice(...);

	# below	is the same as $x->slice("5:7,:,3:4:2")
	$a = $x->mslice([5,7],X,[3,4,2]);

   nslice_if_pdl
       If $self	is a PDL, then calls "slice" with all but the last argument,
       otherwise $self->($_[-1]) is called where $_[-1}	is the original
       argument	string found during PDL::NiceSlice filtering.

       DEVELOPER'S NOTE: this routine is found in Core.pm.PL but would be
       better placed in	Slices/slices.pd.  It is likely	to be moved there
       and/or changed to "slice_if_pdl"	for PDL	3.0.

	$a = $x->nslice_if_pdl(...,'(args)');

   nslice
       c<nslice> was an	internally used	interface for PDL::NiceSlice, but is
       now merely a springboard	to PDL::Slice.	It is deprecated and likely to
       disappear in PDL	3.0.

   inplace
       Flag a piddle so	that the next operation	is done	'in place'

	somefunc($x->inplace); somefunc(inplace	$x);

       In most cases one likes to use the syntax "$y = f($x)", however in many
       case the	operation "f()"	can be done correctly 'in place', i.e. without
       making a	new copy of the	data for output. To make it easy to use	this,
       we write	"f()" in such a	way that it operates in-place, and use
       "inplace" to hint that a	new copy should	be disabled. This also makes
       for clear syntax.

       Obviously this will not work for	all functions, and if in doubt see the
       function's documentation. However one can assume	this is	true for all
       elemental functions (i.e. those which just operate array	element	by
       array element like "log10").

	pdl> $x	= xvals	zeroes 10;
	pdl> log10(inplace $x)
	pdl> p $x
	[-inf 0	   0.30103 0.47712125 0.60205999    0.69897 0.77815125 0.84509804 0.90308999 0.95424251]

   is_inplace
       Test the	in-place flag on a piddle

	 $out =	($in->is_inplace) ? $in	: zeroes($in);
	 $in->set_inplace(0)

       Provides	access to the inplace hint flag, within	the perl millieu.
       That way	functions you write can	be inplace aware... If given an
       argument	the inplace flag will be set or	unset depending	on the value
       at the same time. Can be	used for shortcut tests	that delete the
       inplace flag while testing:

	 $out =	($in->is_inplace(0)) ? $in : zeroes($in); # test & unset!

   set_inplace
       Set the in-place	flag on	a piddle

	 $out =	($in->is_inplace) ? $in	: zeroes($in);
	 $in->set_inplace(0);

       Provides	access to the inplace hint flag, within	the perl millieu.
       Useful mainly for turning it OFF, as inplace turns it ON	more
       conveniently.

   new_or_inplace
	   $a =	new_or_inplace(shift());
	   $a =	new_or_inplace(shift(),$preferred_type);

       Return back either the argument pdl or a	copy of	it depending on
       whether it be flagged in-place or no.  Handy for	building inplace-aware
       functions.

       If you specify a	preferred type (must be	one of the usual PDL type
       strings,	a list ref containing several of them, or a string containing
       several of them), then the copy is coerced into the first preferred
       type listed if it is not	already	one of the preferred types.

       Note that if the	inplace	flag is	set, no	coersion happens even if you
       specify a preferred type.

   new_from_specification
       Internal	method:	create piddle by specification

       This is the argument processing method called by	zeroes and some	other
       functions which constructs piddles from argument	lists of the form:

	[type],	$nx, $ny, $nz,...

       For $nx,	$ny, etc. 0 and	1D piddles are allowed.	 Giving	those has the
       same effect as if saying	"$arg->list", e.g.

	  1, pdl(5,2), 4

       is equivalent to

	  1, 5,	2, 4

       Note, however, that in all functions using "new_from_specification"
       calling "func $piddle" will probably not	do what	you want. So to	play
       safe use	(e.g. with zeroes)

	 $pdl =	zeroes $dimpdl->list;

       Calling

	 $pdl =	zeroes $dimpdl;

       will rather be equivalent to

	 $pdl =	zeroes $dimpdl->dims;

       However,

	 $pdl =	zeroes ushort, $dimpdl;

       will again do what you intended since it	is interpreted as if you had
       said

	 $pdl =	zeroes ushort, $dimpdl->list;

       This is unfortunate and confusing but no	good solution seems obvious
       that would not break existing scripts.

   isnull
       Test whether a piddle is	null

	croak("Input piddle mustn't be null!")
	    if $input_piddle->isnull;

       This function returns 1 if the piddle is	null, zero if it is not. The
       purpose of null piddles is to "tell" any	PDL::PP	methods	to allocate
       new memory for an output	piddle,	but only when that PDL::PP method is
       called in full-arg form.	Of course, there's no reason you couldn't
       commandeer the special value for	your own purposes, for which this test
       function	would prove most helpful.  But in general, you shouldn't need
       to test for a piddle's nullness.

       See "Null PDLs" for more	information.

   isempty
       Test whether a piddle is	empty

	print "The piddle has zero dimension\n"	if $pdl->isempty;

       This function returns 1 if the piddle has zero elements.	This is	useful
       in particular when using	the indexing function which. In	the case of no
       match to	a specified criterion, the returned piddle has zero dimension.

	pdl> $a=sequence(10)
	pdl> $i=which($a < -1)
	pdl> print "I found no matches!\n" if ($i->isempty);
	I found	no matches!

       Note that having	zero elements is rather	different from the concept of
       being a null piddle, see	the PDL::FAQ and PDL::Indexing manpages	for
       discussions of this.

   zeroes
       construct a zero	filled piddle from dimension list or template piddle.

       Various forms of	usage,

       (i) by specification or (ii) by template	piddle:

	# usage	type (i):
	$a = zeroes([type], $nx, $ny, $nz,...);
	$a = PDL->zeroes([type], $nx, $ny, $nz,...);
	$a = $pdl->zeroes([type], $nx, $ny, $nz,...);
	# usage	type (ii):
	$a = zeroes $b;
	$a = $b->zeroes
	zeroes inplace $a;     # Equivalent to	 $a .= 0;
	$a->inplace->zeroes;   #  ""

	pdl> $z	= zeroes 4,3
	pdl> p $z
	[
	 [0 0 0	0]
	 [0 0 0	0]
	 [0 0 0	0]
	]
	pdl> $z	= zeroes ushort, 3,2 # Create ushort array
	[ushort() etc. with no arg returns a PDL::Types	token]

       See also	new_from_specification for details on using piddles in the
       dimensions list.

   zeros
       construct a zero	filled piddle (see zeroes for usage)

   ones
       construct a one filled piddle

	$a = ones([type], $nx, $ny, $nz,...);
	etc. (see 'zeroes')

	see zeroes() and add one

       See also	new_from_specification for details on using piddles in the
       dimensions list.

   reshape
       Change the shape	(i.e. dimensions) of a piddle, preserving contents.

	$x->reshape(NEWDIMS); reshape($x, NEWDIMS);

       The data	elements are preserved,	obviously they will wrap differently
       and get truncated if the	new array is shorter.  If the new array	is
       longer it will be zero-padded.

       ***Potential incompatibility with earlier versions of PDL**** If	the
       list of "NEWDIMS" is empty "reshape" will just drop all dimensions of
       size 1 (preserving the number of	elements):

	 $a = sequence(3,4,5);
	 $b = $a(1,3);
	 $b->reshape();
	 print $b->info;
	PDL: Double D [5]

       Dimensions of size 1 will also be dropped if "reshape" is invoked with
       the argument -1:

	 $b = $a->reshape(-1);

       As opposed to "reshape" without arguments, "reshape(-1)"	preserves
       dataflow:

	 $a = ones(2,1,2);
	 $b = $a(0)->reshape(-1);
	 $b++;
	 print $a;
	[
	 [
	  [2 1]
	 ]
	 [
	  [2 1]
	 ]
	]

       Important: Piddles are changed inplace!

       Note: If	$x is connected	to any other PDL (e.g. if it is	a slice) then
       the connection is first severed.

	pdl> $x	= sequence(10)
	pdl> reshape $x,3,4; p $x
	[
	 [0 1 2]
	 [3 4 5]
	 [6 7 8]
	 [9 0 0]
	]
	pdl> reshape $x,5; p $x
	[0 1 2 3 4]

   squeeze
       eliminate all singleton dimensions (dims	of size	1)

	$b = $a(0,0)->squeeze;

       Alias for "reshape(-1)".	Removes	all singleton dimensions and preserves
       dataflow. A more	concise	interface is provided by PDL::NiceSlice	via
       modifiers:

	use PDL::NiceSlice;
	$b = $a(0,0;-);	# same as $a(0,0)->squeeze

   flat
       flatten a piddle	(alias for "$pdl->clump(-1)")

	 $srt =	$pdl->flat->qsort;

       Useful method to	make a 1D piddle from an arbitrarily sized input
       piddle. Data flows back and forth as usual with slicing routines.
       Falls through if	argument already <= 1D.

   convert
       Generic datatype	conversion function

	$y = convert($x, $newtypenum);

	$y = convert $x, long
	$y = convert $x, ushort

       $newtype	is a type number, for convenience they are returned by
       "long()"	etc when called	without	arguments.

   Datatype_conversions
       byte|short|ushort|long|indx|longlong|float|double (shorthands to
       convert datatypes)

	$y = double $x;	$y = ushort [1..10];
	# all of the above listed shorthands behave similarly

       When called with	a piddle argument, they	convert	to the specific
       datatype.

       When called with	a numeric, list, listref, or string argument they
       construct a new piddle. This is a convenience to	avoid having to	be
       long-winded and say "$x = long(pdl(42))"

       Thus one	can say:

	$a = float(1,2,3,4);	       # 1D
	$a = float q[1 2 3; 4 5	6];    # 2D
	$a = float([1,2,3],[4,5,6]);   # 2D
	$a = float([[1,2,3],[4,5,6]]); # 2D

       Note the	last three give	identical results, and the last	two are
       exactly equivalent - a list is automatically converted to a list
       reference for syntactic convenience. i.e. you can omit the outer	"[]"

       When called with	no arguments, these functions return a special type
       token.  This allows syntactical sugar like:

	$x = ones byte,	1000,1000;

       This example creates a large piddle directly as byte datatype in	order
       to save memory.

       In order	to control how undefs are handled in converting	from perl
       lists to	PDLs, one can set the variable $PDL::undefval; see the
       function	pdl() for more details.

	pdl> p $x=sqrt float [1..10]
	[1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228]
	pdl> p byte $x
	[1 1 1 2 2 2 2 2 3 3]

   byte
       Convert to byte datatype

   short
       Convert to short	datatype

   ushort
       Convert to ushort datatype

   long
       Convert to long datatype

   indx
       Convert to indx datatype

   longlong
       Convert to longlong datatype

   float
       Convert to float	datatype

   double
       Convert to double datatype

   type
       return the type of a piddle as a	blessed	type object

       A convenience function for use with the piddle constructors, e.g.

	$b = PDL->zeroes($a->type,$a->dims,3);
	die "must be float" unless $a->type == float;

       See also	the discussion of the "PDL::Type" class	in PDL::Types.	Note
       that the	"PDL::Type" objects have overloaded comparison and stringify
       operators so that you can compare and print types:

	$a = $a->float if $a->type < float;
	$t = $a->type; print "Type is $t\";

   list
       Convert piddle to perl list

	@tmp = list $x;

       Obviously this is grossly inefficient for the large datasets PDL	is
       designed	to handle. This	was provided as	a get out while	PDL matured.
       It  should now be mostly	superseded by superior constructs, such	as
       PP/threading. However it	is still occasionally useful and is provied
       for backwards compatibility.

	for (list $x) {
	  # Do something on each value...
	}

       If you compile PDL with bad value support (the default),	your machine's
       docs will also say this:

       list converts any bad values into the string 'BAD'.

   unpdl
       Convert piddle to nested	Perl array references

	$arrayref = unpdl $x;

       This function returns a reference to a Perl list-of-lists structure
       equivalent to the input piddle (within the limitation that while	values
       of elements should be preserved,	the detailed datatypes will not	as
       perl itself basically has "number" data rather than byte, short,	int...
       E.g., "sum($x - pdl( $x->unpdl ))" should equal 0.

       Obviously this is grossly inefficient in	memory and processing for the
       large datasets PDL is designed to handle. Sometimes, however, you
       really want to move your	data back to Perl, and with proper
       dimensionality, unlike "list".

	use JSON;
	my $json = encode_json unpdl $pdl;

       If you compile PDL with bad value support (the default),	your machine's
       docs will also say this:

       unpdl converts any bad values into the string 'BAD'.

   listindices
       Convert piddle indices to perl list

	@tmp = listindices $x;

       @tmp now	contains the values "0..nelem($x)".

       Obviously this is grossly inefficient for the large datasets PDL	is
       designed	to handle. This	was provided as	a get out while	PDL matured.
       It  should now be mostly	superseded by superior constructs, such	as
       PP/threading. However it	is still occasionally useful and is provied
       for backwards compatibility.

	for $i (listindices $x)	{
	  # Do something on each value...
	}

   set
       Set a single value inside a piddle

	set $piddle, @position,	$value

       @position is a coordinate list, of size equal to	the number of
       dimensions in the piddle. Occasionally useful, mainly provided for
       backwards compatibility as superseded by	use of slice and assignment
       operator	".=".

	pdl> $x	= sequence 3,4
	pdl> set $x, 2,1,99
	pdl> p $x
	[
	 [ 0  1	 2]
	 [ 3  4	99]
	 [ 6  7	 8]
	 [ 9 10	11]
	]

   at
       Returns a single	value inside a piddle as perl scalar.

	$z = at($piddle, @position); $z=$piddle->at(@position);

       @position is a coordinate list, of size equal to	the number of
       dimensions in the piddle. Occasionally useful in	a general context,
       quite useful too	inside PDL internals.

	pdl> $x	= sequence 3,4
	pdl> p $x->at(1,2)
	7

       If you compile PDL with bad value support (the default),	your machine's
       docs will also say this:

       at converts any bad values into the string 'BAD'.

   sclr
       return a	single value from a piddle as a	scalar

	 $val =	$a(10)->sclr;
	 $val =	sclr inner($a,$b);

       The "sclr" method is useful to turn a piddle into a normal Perl scalar.
       Its main	advantage over using "at" for this purpose is the fact that
       you do not need to worry	if the piddle is 0D, 1D	or higher dimensional.
       Using "at" you have to supply the correct number	of zeroes, e.g.

	 $a = sequence(10);
	 $b = $a->slice('4');
	 print $b->sclr; # no problem
	 print $b->at(); # error: needs	at least one zero

       "sclr" is generally used	when a Perl scalar is required instead of a
       one-element piddle. If the input	is a multielement piddle the first
       value is	returned as a Perl scalar. You can optionally switch on	checks
       to ensure that the input	piddle has only	one element:

	 PDL->sclr({Check => 'warn'}); # carp if called	with multi-el pdls
	 PDL->sclr({Check => 'barf'}); # croak if called with multi-el pdls

       are the commands	to switch on warnings or raise an error	if a
       multielement piddle is passed as	input. Note that these options can
       only be set when	"sclr" is called as a class method (see	example
       above). Use

	 PDL->sclr({Check=>0});

       to switch these checks off again	(default setting); When	called as a
       class method the	resulting check	mode is	returned (0: no	checking, 1:
       warn, 2:	barf).

   cat
       concatenate piddles to N+1 dimensional piddle

       Takes a list of N piddles of same shape as argument, returns a single
       piddle of dimension N+1.

	pdl> $x	= cat ones(3,3),zeroes(3,3),rvals(3,3);	p $x
	[
	 [
	  [1 1 1]
	  [1 1 1]
	  [1 1 1]
	 ]
	 [
	  [0 0 0]
	  [0 0 0]
	  [0 0 0]
	 ]
	 [
	  [1 1 1]
	  [1 0 1]
	  [1 1 1]
	 ]
	]

       If you compile PDL with bad value support (the default),	your machine's
       docs will also say this:

       The output piddle is set	bad if any input piddles have their bad	flag
       set.

       Similar functions include append, which appends only two	piddles	along
       their first dimension, and glue,	which can append more than two piddles
       along an	arbitary dimension.

       Also consider the generic constructor pdl, which	can handle piddles of
       different sizes (with zero-padding), and	will return a piddle of	type
       'double'	by default, but	may be considerably faster (up to 10x) than
       cat.

   dog
       Opposite	of 'cat' :). Split N dim piddle	to list	of N-1 dim piddles

       Takes a single N-dimensional piddle and splits it into a	list of	N-1
       dimensional piddles. The	breakup	is done	along the last dimension.
       Note the	dataflown connection is	still preserved	by default, e.g.:

	pdl> $p	= ones 3,3,3
	pdl> ($a,$b,$c)	= dog $p
	pdl> $b++; p $p
	[
	 [
	  [1 1 1]
	  [1 1 1]
	  [1 1 1]
	 ]
	 [
	  [2 2 2]
	  [2 2 2]
	  [2 2 2]
	 ]
	 [
	  [1 1 1]
	  [1 1 1]
	  [1 1 1]
	 ]
	]

	Break => 1   Break dataflow connection (new copy)

       If you compile PDL with bad value support (the default),	your machine's
       docs will also say this:

       The output piddles are set bad if the original piddle has its bad flag
       set.

   gethdr
       Retrieve	header information from	a piddle

	$pdl=rfits('file.fits');
	$h=$pdl->gethdr;
	print "Number of pixels	in the X-direction=$$h{NAXIS1}\n";

       The "gethdr" function retrieves whatever	header information is
       contained within	a piddle. The header can be set	with sethdr and	is
       always a	hash reference or undef.

       "gethdr"	returns	undef if the piddle has	not yet	had a header defined;
       compare with "hdr" and "fhdr", which are	guaranteed to return a defined
       value.

       Note that gethdr() works	by reference: you can modify the header	in-
       place once it has been retrieved:

	 $a  = rfits($filename);
	 $ah = $a->gethdr();
	 $ah->{FILENAME} = $filename;

       It is also important to realise that in most cases the header is	not
       automatically copied when you copy the piddle.  See hdrcpy to enable
       automatic header	copying.

       Here's another example: a wrapper around	rcols that allows your piddle
       to remember the file it was read	from and the columns could be easily
       written (here assuming that no regexp is	needed,	extensions are left as
       an exercise for the reader)

	sub ext_rcols {
	   my ($file, @columns)=@_;
	   my $header={};
	   $$header{File}=$file;
	   $$header{Columns}=\@columns;

	   @piddles=rcols $file, @columns;
	   foreach (@piddles) {	$_->sethdr($header); }
	   return @piddles;
	}

   hdr
       Retrieve	or set header information from a piddle

	$pdl->hdr->{CDELT1} = 1;

       The "hdr" function allows convenient access to the header of a piddle.
       Unlike "gethdr" it is guaranteed	to return a defined value, so you can
       use it in a hash	dereference as in the example.	If the header does not
       yet exist, it gets autogenerated	as an empty hash.

       Note that this is usually -- but	not always -- What You Want.  If you
       want to use a tied Astro::FITS::Header hash, for	example, you should
       either construct	it yourself and	use "sethdr" to	put it into the
       piddle, or use fhdr instead.  (Note that	you should be able to write
       out the FITS file successfully regardless of whether your PDL has a
       tied FITS header	object or a vanilla hash).

   fhdr
       Retrieve	or set FITS header information from a piddle

	$pdl->fhdr->{CDELT1} = 1;

       The "fhdr" function allows convenient access to the header of a piddle.
       Unlike "gethdr" it is guaranteed	to return a defined value, so you can
       use it in a hash	dereference as in the example.	If the header does not
       yet exist, it gets autogenerated	as a tied Astro::FITS::Header hash.

       Astro::FITS::Header tied	hashes are better at matching the behavior of
       FITS headers than are regular hashes.  In particular, the hash keys are
       CAsE INsEnSItiVE, unlike	normal hash keys.  See Astro::FITS::Header for
       details.

       If you do not have Astro::FITS::Header installed, you get back a	normal
       hash instead of a tied object.

   sethdr
       Set header information of a piddle

	$pdl = zeroes(100,100);
	$h = {NAXIS=>2,	NAXIS1=>100, NAXIS=>100, COMMENT=>"Sample FITS-style header"};
	# add a	FILENAME field to the header
	$$h{FILENAME} =	'file.fits';
	$pdl->sethdr( $h );

       The "sethdr" function sets the header information for a piddle.	You
       must feed in a hash ref or undef, and the header	field of the PDL is
       set to be a new ref to the same hash (or	undefined).

       The hash	ref requirement	is a speed bump	put in place since the normal
       use of headers is to store fits header information and the like.	 Of
       course, if you want you can hang	whatever ugly old data structure you
       want off	of the header, but that	makes life more	complex.

       Remember	that the hash is not copied -- the header is made into a ref
       that points to the same underlying data.	 To get	a real copy without
       making any assumptions about the	underlying data	structure, you can use
       one of the following:

	 use PDL::IO::Dumper;
	 $pdl->sethdr( deep_copy($h) );

       (which is slow but general), or

	 $pdl->sethdr( PDL::_hdr_copy($h) )

       (which uses the built-in	sleazy deep copier), or	(if you	know that all
       the elements happen to be scalars):

	 { my %a = %$h;
	   $pdl->sethdr(\%a);
	 }

       which is	considerably faster but	just copies the	top level.

       The "sethdr" function must be given a hash reference or undef.  For
       further information on the header, see gethdr, hdr, fhdr	and hdrcpy.

   hdrcpy
       switch on/off/examine automatic header copying

	print "hdrs will be copied" if $a->hdrcpy;
	$a->hdrcpy(1);	     # switch on automatic header copying
	$b = $a->sumover;    # and $b will inherit $a's	hdr
	$a->hdrcpy(0);	     # and now make $a non-infectious again

       "hdrcpy"	without	an argument just returns the current setting of	the
       flag.  See also "hcpy" which returns its	PDL argument (and so is	useful
       in method-call pipelines).

       Normally, the optional header of	a piddle is not	copied automatically
       in pdl operations. Switching on the hdrcpy flag using the "hdrcpy"
       method will enable automatic hdr	copying. Note that an actual deep copy
       gets made, which	is rather processor-inefficient	-- so avoid using
       header copying in tight loops!

       Most PDLs have the "hdrcpy" flag	cleared	by default; however, some
       routines	(notably rfits)	set it by default where	that makes more	sense.

       The "hdrcpy" flag is viral: if you set it for a PDL, then derived PDLs
       will get	copies of the header and will also have	their "hdrcpy" flags
       set.  For example:

	 $a = xvals(50,50);
	 $a->hdrcpy(1);
	 $a->hdr->{FOO}	= "bar";
	 $b = $a++;
	 $c = $b++;
	 print $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
	 $b->hdr->{FOO}	= "baz";
	 print $a->hdr->{FOO}, " - ", $b->hdr->{FOO}, "	- ", $c->hdr->{FOO}, "\n";

       will print:

	 bar - bar
	 bar - baz - bar

       Performing an operation in which	more than one PDL has its hdrcpy flag
       causes the resulting PDL	to take	the header of the first	PDL:

	 ($a,$b) = sequence(5,2)->dog;
	 $a->hdrcpy(1);	$b->hdrcpy(1);
	 $a->hdr->{foo}	= 'a';
	 $b->hdr->{foo}	= 'b';
	 print (($a+$b)->hdr->{foo} , ($b+$a)->hdr->{foo});

       will print:

	 a b

   hcpy
       Switch on/off automatic header copying, with PDL	pass-through

	 $a = rfits('foo.fits')->hcpy(0);
	 $a = rfits('foo.fits')->hcpy(1);

       "hcpy" sets or clears the hdrcpy	flag of	a PDL, and returns the PDL
       itself.	That makes it convenient for inline use	in expressions.

   set_autopthread_targ
       Set the target number of	processor threads (pthreads) for multi-
       threaded	processing.

	set_autopthread_targ($num_pthreads);

       $num_pthreads is	the target number of pthreads the auto-pthread process
       will try	to achieve.

       See PDL::ParallelCPU for	an overview of the auto-pthread	process.

	 # Example turning on auto-pthreading for a target of 2	pthreads and for functions involving
	 #   PDLs with greater than 1M elements
	 set_autopthread_targ(2);
	 set_autopthread_size(1);

	 # Execute a pdl function, processing will split into two pthreads as long as
	 #  one	of the pdl-threaded dimensions is divisible by 2.
	 $a = minimum($b);

	 # Get the actual number of pthreads that were run.
	 $actual_pthread = get_autopthread_actual();

   get_autopthread_targ
       Get the current target number of	processor threads (pthreads) for
       multi-threaded processing.

	$num_pthreads =	get_autopthread_targ();

       $num_pthreads is	the target number of pthreads the auto-pthread process
       will try	to achieve.

       See PDL::ParallelCPU for	an overview of the auto-pthread	process.

   get_autopthread_actual
       Get the actual number of	pthreads executed for the last pdl processing
       function.

	$autopthread_actual = get_autopthread_actual();

       $autopthread_actual is the actual number	of pthreads executed for the
       last pdl	processing function.

       See PDL::ParallelCPU for	an overview of the auto-pthread	process.

   set_autopthread_size
       Set the minimum size (in	M-elements or 2^20 elements) of	the largest
       PDL involved in a function where	auto-pthreading	will be	performed. For
       small PDLs, it probably isn't worth starting multiple pthreads, so this
       function	is used	to define a minimum threshold where auto-pthreading
       won't be	attempted.

	set_autopthread_size($size);

       $size is	the mimumum size, in M-elements	or 2^20	elements (approx 1e6
       elements) for the largest PDL involved in a function.

       See PDL::ParallelCPU for	an overview of the auto-pthread	process.

	 # Example turning on auto-pthreading for a target of 2	pthreads and for functions involving
	 #   PDLs with greater than 1M elements
	 set_autopthread_targ(2);
	 set_autopthread_size(1);

	 # Execute a pdl function, processing will split into two pthreads as long as
	 #  one	of the pdl-threaded dimensions is divisible by 2.
	 $a = minimum($b);

	 # Get the actual number of pthreads that were run.
	 $actual_pthread = get_autopthread_actual();

   get_autopthread_size
       Get the current autopthread_size	setting.

	$autopthread_size = get_autopthread_size();

       $autopthread_size is the	mimumum	size limit for auto_pthreading to
       occur, in M-elements or 2^20 elements (approx 1e6 elements) for the
       largest PDL involved in a function

       See PDL::ParallelCPU for	an overview of the auto-pthread	process.

AUTHOR
       Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J.	Lukka,
       (lukka@husc.harvard.edu)	and Christian Soeller
       (c.soeller@auckland.ac.nz) 1997.	 Modified, Craig DeForest
       (deforest@boulder.swri.edu) 2002.  All rights reserved. There is	no
       warranty. You are allowed to redistribute this software / documentation
       under certain conditions. For details, see the file COPYING in the PDL
       distribution. If	this file is separated from the	PDL distribution, the
       copyright notice	should be included in the file.

perl v5.32.0			  2018-05-05			       Core(3)

NAME | DESCRIPTION | SYNOPSIS | VECTORIZATION/THREADING: METHOD AND NOMENCLATURE | VARIABLES | FUNCTIONS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDL::Core&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help