This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PDL/Basic, Next: PDL/CallExt, Prev: PDL/BadValues, Up: Module List Basic utility functions for PDL ******************************* NAME ==== PDL::Basic - Basic utility functions for PDL DESCRIPTION =========== This module contains basic utility functions for creating and manipulating piddles. Most of these functions are simplified interfaces to the more flexible functions in the modules `PDL::Primitive|PDL::Primitive' in this node and `PDL::Slices|PDL::Slices' in this node. SYNOPSIS ======== use PDL::Basic; FUNCTIONS ========= xvals ----- etc. see `zeroes|PDL::Core' in this node. yvals ----- etc. see `zeroes|PDL::Core' in this node. zvals ----- etc. see `zeroes|PDL::Core' in this node. xlinvals -------- xlinvals, ylinvals and zlinvals return a piddle with the same shape as their first argument and linearly scaled values between the two other arguments along the given axis. ylinvals -------- See `xlinvals|' in this node for more information. zlinvals -------- See `xlinvals|' in this node for more information. hist ---- If requested, `$xvals' gives the computed bin centres A nice idiom (with `PDL::Graphics::PGPLOT|PDL::Graphics::PGPLOT' in this node) is bin hist $data; # Plot histogram sequence -------- etc. see `zeroes|PDL::Core' in this node. rvals ----- Centre => [$x,$y,$z...] # Specify centre Center => [$x,$y.$z...] # synonym. For a more general metric, one can define, e.g., sub distance { my ($a,$centre,$f) = @_; my ($r) = $a->allaxisvals-$centre; $f->($r); } sub l1 { sumover(abs($_[0])); } sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); } sub linfty { maximum(abs($_[0])); } so now distance($a, $centre, \&euclid); will emulate rvals, while `\&l1' and `\&linfty' will generate other well-known norms. axisvals -------- This is the routine, for which `xvals|' in this node, `yvals|' in this node etc are mere shorthands. axisvals can be used to fill along any dimension. Note the 'from specification' style (see `zeroes|PDL::Core' in this node) is not available here, for obvious reasons. allaxisvals ----------- allaxisvals produces an array with axis values along each dimension, adding an extra dimension at the start. `allaxisvals($piddle)->slice("($nth)")' will produce the same result as `axisvals($piddle,$nth)' (although with extra work and not inplace). It's useful when all the values will be required, as in the example given of a generalized `rvals|' in this node. transpose --------- Also bound to the `~' unary operator in PDL::Matrix.  File: pm.info, Node: PDL/CallExt, Next: PDL/Char, Prev: PDL/Basic, Up: Module List call functions in external shared libraries ******************************************* NAME ==== PDL::CallExt - call functions in external shared libraries SYNOPSIS ======== use PDL::CallExt; callext('file.so', 'foofunc', $x, $y); # pass piddles to foofunc() % perl -MPDL::CallExt -e callext_cc file.c DESCRIPTION =========== callext() loads in a shareable object (i.e. compiled code) using Perl's dynamic loader, calls the named function and passes a list of piddle arguments to it. It provides a reasonably portable way of doing this, including compiling the code with the right flags, though it requires simple perl and C wrapper routines to be written. You may prefer to use PP, which is much more portable. See *Note PDL/PP: PDL/PP,. You should definitely use the latter for a 'proper' PDL module, or if you run in to the limitations of this module. API === callext_cc() allows one to compile the shared objects using Perl's knowledge of compiler flags. The named function (e.g. 'foofunc') must take a list of piddle structures as arguments, there is now way of doing portable general argument construction hence this limitation. In detail the code in the original file.c would look like this: #include "pdlsimple.h" /* Declare simple piddle structs - note this .h file contains NO perl/PDL dependencies so can be used standalone */ int foofunc(int nargs, pdlsimple **args); /* foofunc prototype */ i.e. foofunc() takes an array of pointers to pdlsimple structs. The use is similar to that of `main(int nargs, char **argv)' in UNIX C applications. pdlsimple.h defines a simple N-dimensional data structure which looks like this: struct pdlsimple { int datatype; /* whether byte/int/float etc. */ void *data; /* Generic pointer to the data block */ int nvals; /* Number of data values */ PDL_Long *dims; /* Array of data dimensions */ int ndims; /* Number of data dimensions */ }; (PDL_Long is always a 4 byte int and is defined in pdlsimple.h) This is a simplification of the internal reprensation of piddles in PDL which is more complicated because of threading, dataflow, etc. It will usually be found somewhere like /usr/local/lib/perl5/site_perl/PDL/pdlsimple.h Thus to actually use this to call real functions one would need to right a wrapper. e.g. to call a 2D image processing routine: void myimage_processer(double* image, int nx, int ny); int foofunc(int nargs, pdlsimple **args) { pdlsimple* image = pdlsimple[0]; myimage_processer( image->data, *(image->dims), *(image->dims+1) ); ... } Obviously a real wrapper would include more error and argument checking. This might be compiled (e.g. Linux): cc -shared -o mycode.so mycode.c In general Perl knows how to do this, so you should be able to get away with: perl -MPDL::CallExt -e callext_cc file.c callext_cc() is a function defined in PDL::CallExt to generate the correct compilation flags for shared objects. If their are problems you will need to refer to you C compiler manual to find out how to generate shared libraries. See t/callext.t in the distribution for a working example. It is up to the caller to ensure datatypes of piddles are correct - if not peculiar results or SEGVs will result. FUNCTIONS ========= callext ------- The file must be compiled with dynamic loading options (see callext_cc). See the module docs `PDL::Callext' for a description of the API. callext_cc ---------- % perl -MPDL::CallExt -e callext_cc file.c -o file.so This works portably because when Perl has built in knowledge of how to do dynamic loading on the system on which it was installed. See the module docs `PDL::Callext' for a description of the API. AUTHORS ======= Copyright (C) Karl Glazebrook 1997. 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.  File: pm.info, Node: PDL/Char, Next: PDL/Complex, Prev: PDL/CallExt, Up: Module List PDL subclass which allows reading and writing of fixed-length character strings as byte PDLs ******************************************************************************************** NAME ==== PDL::Char - PDL subclass which allows reading and writing of fixed-length character strings as byte PDLs SYNOPSIS ======== use PDL; use PDL::Char; my $pchar = PDL::Char->new( [['abc', 'def', 'ghi'],['jkl', 'mno', 'pqr']] ); $pchar->setstr(1,0,'foo'); print $pchar; # 'string' bound to "", perl stringify function # Prints: # [ # ['abc' 'foo' 'ghi'] # ['jkl' 'mno' 'pqr'] # ] print $pchar->atstr(2,0); # Prints: # ghi DESCRIPTION =========== This subclass of PDL allows one to manipulate PDLs of 'byte' type as if they were made of fixed length strings, not just numbers. This type of behavior is useful when you want to work with charactar grids. The indexing is done on a string level and not a character level for the 'setstr' and 'atstr' commands. This module is in particular useful for writing NetCDF files that include character data using the PDL::NetCDF module. FUNCTIONS ========= new --- # Convert a PDL of type 'byte' to a PDL::Char $strpdl1 = PDL::Char->new (sequence (byte, 4, 5)+99); string ------ # 'string' is overloaded to the "" operator, so: # print $char; # should have the same effect. setstr ------ The input string will be null-padded if the string is shorter than the first dimension of the PDL. It will be truncated if it is longer. atstr -----  File: pm.info, Node: PDL/Complex, Next: PDL/Core, Prev: PDL/Char, Up: Module List handle complex numbers ********************** NAME ==== PDL::Complex - handle complex numbers SYNOPSIS ======== use PDL; use PDL::Complex; DESCRIPTION =========== This module features a growing number of functions manipulating complex numbers. These are usually represented as a pair `[ real imag ]' or `[ angle phase ]'. If not explicitly mentioned, the functions can work inplace (not yet implemented!!!) and require rectangular form. While there is a procedural interface available (`$a/$b*$c <=' Cmul (Cdiv $a, $b), $c)>), you can also opt to cast your pdl's into the `PDL::Complex' datatype, which works just like your normal piddles, but with all the normal perl operators overloaded. The latter means that `sin($a) + $b/$c' will be evaluated using the normal rules of complex numbers, while other pdl functions (like max) just treat the piddle as a real-valued piddle with a lowest dimension of size 2, so max will return the maximum of all real and imaginary parts, not the "highest" (for some definition) TIPS, TRICKS & CAVEATS ====================== i is a constant exported by this module, which represents `-1**0.5', i.e. the imaginary unit. it can be used to quickly and conviniently write complex constants like this: `4+3*i'. Use `r2C(real-values)' to convert from real to complex, as in `$r = Cpow $cplx, r2C 2'. The overloaded operators automatically do that for you, all the other functions, do not. So `Croots 1, 5' will return all the fifths roots of 1+1*i (due to threading). use `cplx(real-valued-piddle)' to cast from normal piddles intot he complex datatype. Use `real(complex-valued-piddle)' to cast back. This requires a copy, though. BEWARE: This module has not been extensively tested. Watch out and send me bugreports! EXAMPLE WALK-THROUGH ==================== The complex constant five is equal to `pdl(1,0)': perldl> p $x = r2C 5 [5 0] Now calculate the three roots of of five: perldl> p $r = Croots $x, 3 [ [ 1.7099759 0] [-0.85498797 1.4808826] [-0.85498797 -1.4808826] ] Check that these really are the roots of unity: perldl> p $r ** 3 [ [ 5 0] [ 5 -3.4450524e-15] [ 5 -9.8776239e-15] ] Duh! Could be better. Now try by multiplying $r three times with itself: perldl> p $r*$r*$r [ [ 5 0] [ 5 -2.8052647e-15] [ 5 -7.5369398e-15] ] Well... maybe Cpow (which is used by the `**' operator) isn't as bad as I thought. Now multiply by i and negate, which is just a very expensive way of swapping real and imaginary parts. perldl> p -($r*i) [ [ -0 1.7099759] [ 1.4808826 -0.85498797] [ -1.4808826 -0.85498797] ] Now plot the magnitude of (part of) the complex sine. First generate the coefficients: perldl> $sin = i * zeroes(50)->xlinvals(2,4) + zeroes(50)->xlinvals(0,7) Now plot the imaginary part, the real part and the magnitude of the sine into the same diagram: perldl> line im sin $sin; hold perldl> line re sin $sin perldl> line abs sin $sin Sorry, but I didn't yet try to reproduce the diagram in this text. Just run the commands yourself, making sure that you have loaded `PDL::Complex' (and PDL::Graphics::PGPLOT). FUNCTIONS ========= cplx real-valued-pdl -------------------- Cast a real-valued piddle to the complex datatype. The first dimension of the piddle must be of size 2. After this the usual (complex) arithmetic operators are applied to this pdl, rather than the normal elementwise pdl operators. Dataflow to the complex parent works. Use sever on the result if you don't want this. real cplx-valued-pdl -------------------- Cast a complex vlaued pdl back to the "normal" pdl datatype. Afterwards the normal elementwise pdl operators are used in operations. Dataflow to the real parent works. Use sever on the result if you don't want this. r2C --- i2C --- Cr2p ---- Cp2r ---- Cmul ---- Cscale ------ Cdiv ---- Ccmp ---- Cconj ----- Cabs ---- Cabs2 ----- Carg ---- Csin ---- Ccos ---- Ctan a [not inplace] -------------------- tan (a) = -i * (exp (a*i) - exp (-a*i)) / (exp (a*i) + exp (-a*i)) Cexp ---- Clog ---- Cpow ---- Csqrt ----- BEGIN {*Csqrt = \&PDL::Csqrt; } Casin ----- BEGIN {*Casin = \&PDL::Casin; } Cacos ----- BEGIN {*Cacos = \&PDL::Cacos; } Catan cplx [not inplace] ------------------------ Return the complex `atan()'. Csinh ----- Ccosh ----- Ctanh ----- BEGIN {*Ctanh = \&PDL::Ctanh; } Casinh ------ BEGIN {*Casinh = \&PDL::Casinh; } Cacosh ------ BEGIN {*Cacosh = \&PDL::Cacosh; } Catanh ------ BEGIN {*Catanh = \&PDL::Catanh; } Cproj ----- Croots ------ re cplx, im cplx ---------------- Return the real or imaginary part of the complex number(s) given. These are slicing operators, so data flow works. The real and imaginary parts are returned as piddles (ref eq PDL). rCpolynomial ------------ AUTHOR ====== Copyright (C) 2000 Marc Lehmann . All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation as described in the file COPYING in the PDL distribution. SEE ALSO ======== perl(1), *Note PDL: PDL,.  File: pm.info, Node: PDL/Core, Next: PDL/Core/Dev, Prev: PDL/Complex, Up: Module List fundamental PDL functionality ***************************** NAME ==== PDL::Core - fundamental PDL functionality 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 FUNCTIONS ========= pdl --- 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 [] `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. null ---- `null()' has a special meaning to `PDL::PP|PDL::PP' in this node. 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). nullcreate ---------- This is an routine used by many of the threading primitives (i.e. `sumover|PDL::Primitive' in this node, `minimum|PDL::Primitive' in this node, 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. nelem ----- dims ---- PDL::getndims ------------- PDL::getdim ----------- 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 ----- The difference between `pdl()|' in this node 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 particulary 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'. PDL::get_datatype ----------------- Mainly used for internal routines. NOTE: get_datatype returns 'just a number' not any special type object, unlike `type|' in this node. howbig ------ Mainly used for internal routines. NOTE: NOT a method! This is because get_datatype returns 'just a number' not any special object. threadids --------- doflow ------ flows ----- PDL::new -------- Constructs piddle from perl numbers and lists. PDL::copy --------- Since `$new = $old' just makes a new reference, the copy method is provided to allow real independent copies to be made. PDL::unwind ----------- PDL::make_physical ------------------ 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|PDL::Indexing' in this node). 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 neccessary 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|PDL::PP' in this node) which can be used to transparently access virtual piddles without the need to physicalise them (though there are exceptions). dummy ----- 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. thread_define ------------- thread_define provides some support for threading (see *Note PDL/Indexing: PDL/Indexing,) at the perl level. It allows you to do things for which you normally would have resorted to PDL::PP (see *Note PDL/PP: 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 *Note PDL/Indexing: PDL/Indexing, and *Note PDL/PP: 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 *Note PDL/Indexing: 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|PDL::Graphics::TriD::VRML' in this node 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|PDL::PP' in this node for the format of the signature. Currently, the `[t]' qualifier and all type qualifiers are ignored. PDL::thread ----------- Same as `PDL::thread1|' in this node, i.e. uses thread id 1. diagonal -------- PDL::thread1 ------------ Convenience function interfacing to `PDL::Slices::threadI|PDL::Slices' in this node. PDL::thread2 ------------ Convenience function interfacing to `PDL::Slices::threadI|PDL::Slices' in this node. PDL::thread3 ------------ Convenience function interfacing to `PDL::Slices::threadI|PDL::Slices' in this node. sever ----- 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. This is simply achieved by using sever. For example, In this regard it acts 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. $a = zeroes(20); $a->sever; # NOOP since $a is already its own boss! PDL::info --------- 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 `%' 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) 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 mslice ------ inplace ------- 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::new_from_specification --------------------------- This is the argument processing method called by `zeroes|' in this node 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. 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. perldl> $a=sequence(10) perldl> $i=which($a < -1) perldl> print "I found no matches!\n" if ($a->isempty); Note that having zero elements is rather different from the concept of being a null piddle, see the `PDL::FAQ|PDL::FAQ' in this node and `PDL::Indexing|PDL::Indexing' in this node manpages for discussions of this. zeroes ------ Various forms of usage, (i) by specification or (ii) by template piddle: See also `new_from_specification|new_from_specification' in this node for details on using piddles in the dimensions list. ones ---- See also `new_from_specification|new_from_specification' in this node for details on using piddles in the dimensions list. reshape ------- 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. Note: an explicit copy is forced - this is the only way (for now) of stopping a crash if $x is a slice. flat ---- Useful method to make a 1D piddle from an arbitrarily sized input piddle. Data flows back and forth as usual with slicing routines. convert ------- `$newtype' is a type number, for convenience they are returned by `long()' etc when called without arguments. Datatype_conversions -------------------- When called with a piddle argument, they convert to the specific datatype. When called with a numeric or list / listref 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([1,2,3],[4,5,6]); # 2D $a = float([[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 [] When called with no arguments 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()|' in this node for more details. byte ---- short ----- ushort ------ long ---- float ----- double ------ type ---- A convenience function for use with the piddle constructors, e.g. See the discussion of the `PDL::Type' object in *Note PDL/Types: PDL/Types,. list ---- 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. listindices ----------- `@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. set --- `@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|PDL::Slices' in this node and assigment operator `.='. at -- `@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. cat --- Takes a list of N piddles of same shape as argument, returns a single piddle of dimension N+1 dog --- 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.: barf ---- `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. It does this magic by unwinding the stack frames until it reaches a package NOT beginning with `"PDL::"'. If you DO want it to report errors in some module PDL::Foo (e.g. when debugging PDL::Foo) then set the variable `$PDL::Foo::Debugging=1'. Additionally if you set the variable `$PDL::Debugging=1' you will get a COMPLETE stack trace back up to the top level package. Finally `barf()' will try and report usage information from the PDL documentation database if the error message is of the form 'Usage: func'. Remember `barf()' is your friend. *Use* it! 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 gethdr ------ The gethdr function retrieves whatever header information is contained within a piddle. The header can be set with `sethdr|' in this node and is always a hash reference and has to be dereferenced for access to the value. It is important to realise that you are free to insert whatever hash reference you want in the header, so you can use it to record important information about your piddle, and that it is not automatically copied when you copy the piddle. See `hdrcpy|' in this node to enable automatic header copying. For instance 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; } sethdr ------ The sethdr function sets the header information for a piddle. Normally you would get the current header information with `gethdr|' in this node, add/change/remove fields, then apply those changes with sethdr. The sethdr function must be given a hash reference. For further information on the header, see `gethdr|' in this node and `hdrcpy|' in this node. hdrcpy ------ 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 copying is *by reference* for efficiency reasons. hdrcpy without an argument just returns the current setting of the flag. 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. 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.  File: pm.info, Node: PDL/Core/Dev, Next: PDL/Dataflow, Prev: PDL/Core, Up: Module List PDL development module ********************** NAME ==== PDL::Core::Dev - PDL development module DESCRIPTION =========== This module encapsulates most of the stuff useful for PDL development and is often used from within Makefile.PL's. SYNOPSIS ======== use PDL::Core::Dev; if ($^O =~ /win32/i) { warn "Win32 systems not yet supported. Will not build PDL::IO::Browser"; write_dummy_make(unsupported('PDL::XXX','win32')); return; } FUNCTIONS ========= isbigendian ----------- returns 1 if the machine is big endian, 0 if little endian, or dies if neither. It uses the `byteorder' element of perl's `%Config' array. trylink ------- Try to link some C-code making up the body of a function with a given set of library specifiers return 1 if successful, 0 otherwise Takes 4 + 1 optional argument. * an informational message to print (can be empty) * any commands to be included at the top of the generated C program (typically something like `#include "mylib.h"') * the body of the program (in function main) * library flags to use for linking. Preprocessing by MakeMaker should be performed as needed (see options and example). * OPTIONS 1. Preprocess library in the way MakeMaker does things. This is advisable to ensure that your code will actually work after the link specs have been processed by MakeMaker. 2. Hide Controls of linking output etc is hidden from the user or not. On by default.  File: pm.info, Node: PDL/Dataflow, Next: PDL/Dbg, Prev: PDL/Core/Dev, Up: Module List description of the dataflow philosophy ************************************** NAME ==== PDL::Dataflow - description of the dataflow philosophy SYNOPSIS ======== perldl> $a = zeroes(10); perldl> $b = $a->slice("2:4:2"); perldl> $b ++; perldl> print $a; [0 0 1 0 1 0 0 0 0 0] WARNING ======= Dataflow is very experimental. Many features of it are disabled for 2.0, particularly families for one-directional dataflow. If you wish to use one-directional dataflow for something, please contact the author first and we'll work out how to make it functional again. Two-directional dataflow (which implements ->slice() etc.) is fully functional, however. Just about any function which returns some subset of the values in some piddle will make a binding so that $a = some piddle $b = $a->slice("some parts"); $b->set(3,3,10); also changes the corresponding element in $a. $b has become effectively a window to some subelements of $a. You can also define your own routines that do different types of subsets. If you don't want $b to be a window to $a, you must do $b = $a->slice("some parts")->copy; The copying turns off all dataflow between the two piddles. The difficulties with one-directional dataflow are related to sequences like $b = $a + 1; $b ++; where there are several possible outcomes and the semantics get a little murky. DESCRIPTION =========== Dataflow is new to PDL2.0. The basic philosophy behind dataflow is that > $a = pdl 2,3,4; > $b = $a * 2; > print $b [2 3 4] > $a->set(0,5); > print $b; [10 3 4] should work. It doesn't. It was considered that doing this might be too confusing for novices and occasional users of the language. Therefore, you need to explicitly turn on dataflow, so > $a = pdl 2,3,4; > $a->doflow(); > $b = $a * 2; ... produces the (un)expected result. The rest of this documents explains various features and details of the dataflow implementation. Lazy evaluation =============== When you calculate something like the above > $a = pdl 2,3,4; > $a->doflow(); > $b = $a * 2; nothing will have been calculated at this point. Even the memory for the contents of $b has not been allocated. Only the command > print $b will actually cause $b to be calculated. This is important to bear in mind when doing performance measurements and benchmarks as well as when tracking errors. There is an explanation for this behaviour: it may save cycles but more importantly, imagine the following: > $a = pdl 2,3,4; > $b = pdl 5,6,7; > $c = $a + $b; ... > $a->resize(4); > $b->resize(4); > print $c; Now, if $c were evaluated between the two resizes, an error condition of incompatible sizes would occur. What happens in the current version is that resizing $a raises a flag in $c: "PDL_PARENTDIMSCHANGED" and $b just raises the same flag again. When $c is next evaluated, the flags are checked and it is found that a recalculation is needed. Of course, lazy evaluation can sometimes make debugging more painful because errors may occur somewhere where you'd not expect them. A better stack trace for errors is in the works for PDL, probably so that you can toggle a switch $PDL::traceevals and get a good trace of where the error actually was. Families ======== This is one of the more intricate concepts of one-directional dataflow. Consider the following code ($a and $b are pdls that have dataflow enabled): $c = $a + $b; $e = $c + 1; $d = $c->diagonal(); $d ++; $f = $c + 1; What should $e and $f contain now? What about when $a is changed and a recalculation is triggered. In order to make dataflow work like you'd expect, a rather strange concept must be introduced: families. Let us make a diagram: a b \ / c /| / | e d This is what PDL actually has in memory after the first three lines. When $d is changed, we want $c to change but we don't want $e to change because it already is on the graph. It may not be clear now why you don't want it to change but if there were 40 lines of code between the 2nd and 4th lines, you would. So we need to make a copy of $c and $d: a b \ / c' . . . c /| |\ / | | \ e d' . . . d f Notice that we primed the original c and d, because they do not correspond to the objects in $c and $d any more. Also, notice the dotted lines between the two objects: when $a is changed and this diagram is re-evaluated, $c really does get the value of c' with the diagonal incremented. To generalize on the above, whenever a piddle is mutated i.e. when its actual *value* is forcibly changed (not just the reference: $d = $d + 1 would produce a completely different result ($c and $d would not be bound any more whereas $d .= $d + 1 would yield the same as $d++), a "family" consisting of all other piddles joined to the mutated piddle by a two-way transformation is created and all those are copied. All slices or transformations that simply select a subset of the original pdl are two-way. Matrix inverse should be. No arithmetic operators are. Sources ======= What you were told in the previous section is not quite true: the behaviour described is not *always* what you want. Sometimes you would probably like to have a data "source": $a = pdl 2,3,4; $b = pdl 5,6,7; $c = $a + $b; line($c); Now, if you know that $a is going to change and that you want its children to change with it, you can declare it into a data source (XXX unimplemented in current version): $a->datasource(1); After this, $a++ or $a .= something will not create a new family but will alter $a and cut its relation with its previous parents. All its children will follow its current value. So if $c in the previous section had been declared as a source, $e and $f would remain equal. Binding ======= A dataflow mechanism would not be very useful without the ability to bind events onto changed data. Therefore, we provide such a mechanism: > $a = pdl 2,3,4 > $b = $a + 1; > $c = $b * 2; > $c->bind( sub { print "A now: $a, C now: $c\n" } ) > PDL::dowhenidle(); A now: [2,3,4], C now: [6 8 10] > $a->set(0,1); > $a->set(1,1); > PDL::dowhenidle(); A now: [1,1,4], C now: [4 4 10] Notice how the callbacks only get called during PDL::dowhenidle. An easy way to interface this to Perl event loop mechanisms (such as Tk) is being planned. There are many kinds of uses for this feature: self-updating graphs, for instance. Bla bla bla XXX more explanation Limitations =========== Dataflow as such is a fairly limited addition on top of Perl. To get a more refined addition, the internals of perl need to be hacked a little. A true implementation would enable flow of everything, including data data size datatype operations At the moment we only have the first two (hey, 50% in a couple of months is not bad ;) but even this is useful by itself. However, especially the last one is desirable since it would add the possibility of flowing closures from place to place and would make many things more flexible. To get the rest working, the internals of dataflow probably need to be changed to be a more general framework. Additionally, it would be nice to be able to flow data in time, lucid-like (so you could easily define all kinds of signal processing things). AUTHOR ====== Copyright(C) 1997 Tuomas J. Lukka (lukka@fas.harvard.edu). Redistribution in the same form is allowed provided that the copyright notice stays intact but reprinting requires a permission from the author.  File: pm.info, Node: PDL/Dbg, Next: PDL/Delta, Prev: PDL/Dataflow, Up: Module List functions to support debugging of PDL scripts ********************************************* NAME ==== PDL::Dbg - functions to support debugging of PDL scripts SYNOPSIS ======== use PDL; use PDL::Dbg; $c = $a->slice("5:10,2:30")->px->diagonal(3,4); PDL->px; DESCRIPTION =========== This packages implements a couple of functions that should come in handy when debugging your PDL scripts. They make a lot of sense while you're doing rapid prototyping of new PDL code, let's say inside the perldl shell. FUNCTIONS ========= px -- This function prints some information about piddles. It can be invoked as a class method (e.g. `PDL->px' ) or as an instance method (e.g. `$pdl->px($arg)'). If invoked as a class method it prints info about all piddles found in the current package (*excluding* my variables). This comes in quite handy when you are not quite sure which pdls you have already defined, what data they hold , etc. px is supposed to support inheritance and prints info about all symbols for which an `isa($class)' is true. An optional string argument is interpreted as the package name for which to print symbols: perldl> PDL->px('PDL::Mypack') The default package is that of the caller. invoked as an instance method it prints info about that particular piddle if `$PDL::debug' is true and returns the pdl object upon completion. It accepts an optional string argument that is simply prepended to the default info if it doesn't contain a % character. If, however, the argument contains a % then the string is passed to the info method to control the format of the printed information. This can be used to achieve customized output from px. See the documentation of PDL::info for further details. The output of px will be determined by the default formatting string that is passed to the info method (unless you pass a string containing % to px when invoking as an instance method, see above). This default string is stored in `$PDL::Dbg::Infostr' and the default output format can be accordingly changed by setting this variable. If you do this you should also change the default title string that the class method branch prints at the top of the listing to match your new format string. The default title is stored in the variable `$PDL::Dbg::Title'. For historical reasons vars is an alias for px. vars ---- BUGS ==== There are probably some. Please report if you find any. Bug reports should be sent to the PDL mailing list perldl@jachw.hawaii.edu. AUTHOR ====== Copyright(C) 1997 Christian Soeller (c.soeller@auckland.ac.nz). 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.  File: pm.info, Node: PDL/Delta, Next: PDL/Doc, Prev: PDL/Dbg, Up: Module List PDL changes between V1.0 and V2.0 ********************************* NAME ==== PDL::Delta - PDL changes between V1.0 and V2.0 DESCRIPTION =========== This file is an attempt to list the major user-visible changes between PDL versions 1.0 and 2.0. Core Changes ============ Piddles are not hashes any more: -------------------------------- $a = zeroes 10,10; $$a{FOO} = "bar" doesn't work. They are currently scalar references (to opaque C structures in finer terms) because of speed as well as syntactic issues. If you want to have a hash, use $a->hdr() which returns a reference to an anonymous hash. Also, subclassing works if you store a piddle in the hash member "PDL". There are also many core enhancements to support Dataflow and Slicing tricks, but these do not introduce any incompatbilities. Incompatible Changes vs 1.11 ---------------------------- rgrep Order of the arguments has changed. copy method No longer copies the header. This may not be a misfeature. Documentation Changes ===================== Many of the base and library pods were updated. SEE ALSO ======== The Changes file for exhaustive details on what changed. The INSTALL file for how to build PDL. The README file for general stuff. HISTORY ======= pdldelta was inspired by *perldelta* man page in the perl 5.004 distribution.  File: pm.info, Node: PDL/Doc, Next: PDL/Doc/Perldl, Prev: PDL/Delta, Up: Module List support for PDL online documentation ************************************ NAME ==== PDL::Doc - support for PDL online documentation SYNOPSIS ======== use PDL::Doc; $onlinedc = new PDL::Doc ($docfile); @match = $onlinedc->search('m/slice|clump/'); DESCRIPTION =========== An implementation of online docs for PDL. PDL documentation conventions ============================= For a package like PDL that has *a lot* of functions it is very desirable to have some form of online help to make it easy for the user to remind himself of names, calling conventions and typical usage of the multitude of functions at his disposal. To make it straightforward to extract the relevant information from the POD documentation in source files that make up the PDL distribution certain conventions have been adopted in formatting this documentation. The first convention says that all documentation for PDL functions appears in the POD section introduced by =head1 FUNCTIONS Individual functions in this section are introduced by =head2 funcname where signature is the argumentlist for a PP defined function as explained in *Note PDL/PP: PDL/PP,. Generally, PDL documentation is in valid POD format (see *Note Perlpod: (perl.info)perlpod,) but uses the =for directive in a special way. The =for directive is used to flag to the PDL Pod parser that information is following that will be used to generate online help. The PDL podparser is derived from the PDL::Pod::Parser class that had to be patched in a few places, partly to fix minor bugs, partly to enhance functionality for perusal by PDL::Doc. Since the PDL::Doc module is still experimental the patched Pod-Parser distribution is included with the current PDL-Doc distribution. Note that PDL::Doc will not work correctly with the released Pod-Parser distribution. The PDL Pod parser recognises the following =for directives: Ref indicates that the one line reference for this function follows, e.g., =for ref Returns a piddle of lags to parent. Sig the signature for the current function follows, e.g., =for sig Signature: (a(n), [o]b(), [t]tmp(n)) Usage an indication of the possible calling conventions for the current function, e.g., =for usage wpic($pdl,$filename[,{ options... }]) Opt lists options for the current function, e.g., =for options CONVERTER => 'ppmtogif', # explicitly specify pbm converter FLAGS => '-interlaced -transparent 0', # flags for converter IFORM => 'PGM', # explicitly specify intermediate format XTRAFLAGS => '-imagename iris', # additional flags to defaultflags FORMAT => 'PCX', # explicitly specify output image format COLOR => 'bw', # specify color conversion LUT => $lut, # use color table information Example gives examples of typical usage for the current function: =for example wpic $pdl, $file; $im->wpic('web.gif',{LUT => $lut}); for (@images) { $_->wpic($name[0],{CONVERTER => 'ppmtogif'}) } Bad provides information on how the function handles bad values (if `$PDL:Config{WITH_BADVAL}' is set to 1). The intention is to have this information automatically created for pp-compiled functions, although it can be over-ridden. The PDL podparser is implemented as a simple state machine. Any of the above =for statements switches the podparser into a state where the following paragraph is accepted as information for the respective field (Ref, Usage, Opt, Example or Bad). Only the text up to the end of the current paragraph is accepted, for example: =for example ($x,$y) = $a->func(1,3); # this is part of the accepted info $x = func($a,0,1); # this as well $x = func($a,$b); # but this isn't To make the resulting pod documentation also easily digestible for the existing pod filters (pod2man, pod2text, pod2html, etc) the actual textblock of information must be separated from the =for directive by at least one blank line. Otherwise, the textblock will be lost in the translation process when the "normal" podformatters are used. The general idea behind this format is that it should be easy to extract the information for online documentation, automatic generation of a reference card, etc but at the same time the documentation should be translated by the standard podformatters without loss of contents (and without requiring any changes in the existing POD format). The preceding explanations should be further explained by the following example (extracted from PDL/IO/Misc/misc.pd): =head2 rcols() =for ref Read ASCII whitespaced cols from file into piddles efficiently. If no columns are specified all are assumed Will optionally only process lines matching a pattern. Can take file name or *HANDLE. =for usage Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...) e.g., =for example ($x,$y) = rcols 'file1' ($x,$y,$z) = rcols 'file2', "/foo/",3,4 $x = PDL->rcols 'file1'; Note: currently quotes are required on the pattern. which is translated by, e.g, the standard `pod2text' converter into: rcols() Read ASCII whitespaced cols from file into piddles efficiently. If no columns are specified all are assumed Will optionally only process lines matching a pattern. Can take file name or *HANDLE. Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...) e.g., ($x,$y) = rcols 'file1' ($x,$y,$z) = rcols 'file2', "/foo/",3,4 $x = PDL->rcols 'file1'; Note: currently quotes are required on the pattern. It should be clear from the preceding example that readable output can be obtained from this format using the standard converters and the reader will hopefully get a feeling how he can easily intersperse the special =for directives with the normal POD documentation. Which directives should be contained in the documentation --------------------------------------------------------- The module documentation should start with the =head1 NAME PDL::Modulename -- do something with piddles section (as anyway required by pod2man) since the PDL podparser extracts the name of the module this function belongs to from that section. Each function that is not only for internal use by the module should be documented, introduced with the =head2 directive in the `=head1 FUNCTIONS' section. The only field that every function documented along these lines should have is the Ref field preceding a one line description of its intended functionality (suitable for inclusion in a concise reference card). PP defined functions (see *Note PDL/PP: PDL/PP,) should have a Sig field stating their signature. To facilitate maintainance of this documentation for such functions the 'Doc' field has been introduced into the definition of `pp_def' (see again *Note PDL/PP: PDL/PP,) which will take care that name and signature of the so defined function are documented in this way (for examples of this usage see, for example, the PDL::Slices module, especially `slices.pd' and the resulting `Slices.pm'). Similarly, the 'BadDoc' field provides a means of specifying information on how the routine handles the presence of bad values: this will be autpmatically created if BadDoc is not supplied, or set to undef. Furthermore, the documentation for each function should contain at least one of the Usage or Examples fields. Depending on the calling conventions for the function under consideration presence of both fields may be warranted. If a function has options that should be given as a hash reference in the form {Option => Value, ...} then the possible options (and aproppriate values) should be explained in the textblock following the `=for Opt' directive (see example above and, e.g., PDL::IO::Pic). It is well possible that some of these conventions appear to be clumsy at times and the author is keen to hear of any suggestions for better alternatives. INSTANCE METHODS ================ new --- $onlinedc = new PDL::Doc ('file.pdl',[more files]); addfiles -------- add another file to the online database associated with this object. outfile ------- set the name of the output file for this online db ensuredb -------- Make sure that the database is slurped in savedb ------ save the database (i.e., the hash of PDL symbols) to the file associated with this object. gethash ------- Return the PDL symhash (e.g. for custom search operations) search ------ Search a PDL symhash Searching is by default case insensitive. Other flags can be given by specifying the regexp in the form `m/regex/ismx' where / can be replaced with any other non-alphanumeric character. $fields is an array reference for all hash fields that should be matched against the regex. Valid fields are Name, # name of the function Module, # module the function belongs to Ref, # the one-line reference description Example, # the example for this function Opt, # options File, # the path to the source file this docs have been extracted from scan ---- Scan a source file using the PDL podparser to extract information for online documentation scantree -------- Scan whole directory trees for online documentation in `.pm' (module definition) and `*.pod' (general documentation) files (using the File::Find module). funcdocs -------- extract the complete documentation about a function from its source file using the PDL::Pod::Parser filter. FUNCTIONS ========= BUGS ==== Quite a few shortcomings which will hopefully be fixed following discussions on the pdl-porters mailing list. AUTHOR ====== Copyright 1997 Christian Soeller and Karl Glazebrook 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.