Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for pdl::faq (redhat section 1)

FAQ(1)			       User Contributed Perl Documentation			   FAQ(1)

NAME
       PDL::FAQ - Frequently asked questions about PDL

VERSION
       Current FAQ version:  0.6

DESCRIPTION
       This is version	0.6 of the PDL FAQ, a collection of  frequently asked questions about PDL
       - the Perl Data Language.

ABOUT THIS DOCUMENT
       Q: 1.1	 Where to find this document

       You can find the latest version of this document at http://pdl.perl.org/faq.html .  This
       FAQ will be monthly posted to the PDL mailing list perldl@jach.hawaii.edu .

       Q: 1.2	 How to contribute to this document

       This is a considerably reworked version of the PDL FAQ. As such many errors might have
       crept in and many updates might not have made it in.  You are explicitly encouraged to let
       us know about questions which you think should be answered in this document but currently
       aren't. Similarly, if you think parts of this document are unclear, please tell the FAQ
       maintainer about it. Where a specific answer is taken in full from someone's posting the
       authorship should be indicated, let the FAQ maintainer know if it isn't. For more general
       information explicit acknowledgement is not made in the text, but rather there is an
       incomplete list of contributors at the end of this docuement. Please contact the FAQ main-
       tainer if you feel hard done by.

       Send your comments, additions, suggestions or corrections to the PDL mailing list at
       perldl@jach.hawaii.edu or to the FAQ maintainer Jarle Brinchmann ( jarle@astro.ox.ac.uk ).
       See below for instructions on how to join the mailing lists.

GENERAL QUESTIONS
       Q: 2.1	 What is PDL ?

       PDL stands for  Perl Data  Language . To say it with the words of Karl Glazebrook, initia-
       tor of the PDL project:

	       The PDL concept is to give standard perl5 the ability
	       to COMPACTLY store and SPEEDILY manipulate the large
	       N-dimensional data sets which are the bread and butter
	       of scientific computing. e.g. $a=$b+$c can add two
	       2048x2048 images in only a fraction of a second.

       It is hoped to eventually provide tons of useful functionality for scientific and numeric
       analysis.

       For readers familiar with other scientific data evaluation packages it may be helpful to
       add that PDL is in many respects similar to IDL, MATLAB and similar packages. However, it
       tries to improve on a number of issues which were perceived (by the authors of PDL) as
       shortcomings of those existing packages.

       Q: 2.2	 Who supports PDL? Who develops it?

       PDL is supported by its users. General informal support for PDL is provided through the
       PDL mailing list ( perldl@jach.hawaii.edu , see below).

       As a Perl extension (see below) it is devoted to the idea of free and open development put
       forth by the Perl community. PDL was and is being actively developed by a loosely knit
       group of people around the world who coordinate their activities through the PDL develop-
       ment mailing list ( pdl-porters@jach.hawaii.edu , see below). If you would like to join in
       the ongoing efforts to improve PDL please join this list.

       Q: 2.3	 Why yet another Data Language ?

       There are actually several reasons and everyone should decide for himself which are the
       most important ones:

       o   PDL is " free software " . The authors of PDL think that this concept has several
	   advantages: everyone has access to the sources - > better debugging, easily adaptable
	   to your own needs, extensible for your purposes, etc... In comparison with commercial
	   packages such as Matlab and IDL this is of considerable importance for workers who
	   want to do some work at home and cannot afford the considerable cost to buy commercial
	   packages for personal use.

       o   PDL is based on a powerful and well designed scripting language: Perl. In contrast to
	   other scientific/numeric data analysis languages it has been designed using the lan-
	   guage features of a proven language instead of having grown into existence from
	   scratch defining the control structures while features were added during development
	   (leading to languages that often appear clumsy and badly planned for most existing
	   packages with similar scope as PDL).

       o   Using Perl as the basis a PDL programmer has all the powerful features of Perl at his
	   hand, right from the start. This includes regular expressions, associative arrays
	   (hashes), well designed interfaces to the operating system, network, etc. Experience
	   has shown that even in mainly numerically oriented programming it is often extremely
	   handy if you have easy access to powerful semi-numerical or completely non-numerical
	   functionality as well. For example, you might want to offer the results of a compli-
	   cated computation as a server process to other processes on the network, perhaps
	   directly accepting input from other processes on the network. Using Perl and existing
	   Perl extension packages things like this are no problem at all (and it all will fit
	   into your " PDL script " ).

       o   Extremely easy extensibility and interoperability as PDL is a Perl extension; develop-
	   ment support for Perl extensions is an integral part of Perl and there are already
	   numerous extensions to standard Perl freely available on the network.

       o   Integral language features of Perl (regular expressions, hashes, object modules)
	   immensely facilitated development and implementation of key concepts of PDL. One of
	   the most striking examples for this point is probably PDL::PP (see below), a code gen-
	   erator/parser/pre-processor that generates PDL functions from concise descriptions.

       o   None of the existing DLs follow the Perl language rules, which the authors firmly
	   believe in:

	   o   TIMTOWTDI: There is more than one way to do it.	Minimalist languages are inter-
	       esting for computer scientists, but for users, a little bit of redundancy makes
	       things wildly easier to cope with and allows individual programming styles - just
	       as people speak in different ways. For many people this will undoubtedly be a rea-
	       son to avoid PDL ;)

	   o   Simple things are simple, complicated things possible: Things that are often done
	       should be easy to do in the language, whereas seldom done things shouldn't be too
	       cumbersome.

	   All existing languages violate at least one of these rules.

       o   As a project for the future PDL should be able to use super computer features, e.g.
	   vector capabilities/parallel processing. This will probably be achieved by having
	   PDL::PP (, see below) generate appropriate code on such architectures to exploit these
	   features.

       o   [ fill in your personal 111 favourite reasons here...]

       Q: 2.4	 What is PDL good for ?

       Just in case you do not yet know what the main features of PDL are and what one could do
       with them, here is a (necessarily selective) list of key features:

       PDL is well suited for matrix computations, general handling of multidimensional data,
       image processing, general scientific computation, numerical applications. It supports I/O
       for many popular image and data formats, 1D (line plots), 2D (images) and 3D (volume visu-
       alisation, surface plots via OpenGL - for instance impelmented using Mesa), graphics dis-
       play capabilities and implements lots of numerical and semi-numerical algorithms.

       Through the powerful pre-processor it is also easy to interface Perl to your favourite C
       routines, more of that further below.

       Q: 2.5	 What is the connection between PDL and Perl ?

       PDL is a Perl5 extension package. As such it needs an existing Perl5 installation (see
       below) to run. Furthermore, much of PDL is written in perl (+ some core functionality that
       is written in C). PDL programs are (syntactically) just perl scripts that happen to use
       some of the functionality implemented by the package " PDL " ;

       Q: 2.6	 What do I need to run PDL on my machine ?

       Since PDL is just a Perl package you need first of all an installation of Perl on your
       machine. As of this writing PDL requires version 5.004 of Perl, version 5.004_4 or higher
       is  strongly recommended. More information on where and how to get a Perl installation can
       be found at the Perl home page http://www.perl.com and at many CPAN sites (if you do not
       know what  CPAN is check the answer to the next question).

       To build PDL you also need a working C compiler and support for Xsubs the package Extu-
       tils::MakeMaker.  See also http://pdl.perl.org/ports.html for a list of machines where PDL
       has been tested. If you don't have a compiler there might be a binary distribution avail-
       abe, see "Binary distributions" below.

       If you can (or cannot) get PDL working on a new (previously unsupported) platform we would
       like to hear about it. Please, report your success/failure to the PDL mailing list at
       perldl@jach.hawaii.edu . We will do our best to assist you in porting PDL to a new system.

       Q: 2.7	 Where do I get it?

       PDL is available as source distribution in the  Comprehensive Perl Archive Network , or
       CPAN.  This archive contains not only the PDL distribution but also just about everything
       else that is Perl-related. CPAN is mirrored by dozens of sites all over the world. The
       main site is ftp://ftp.funet.fi . You can find a more local CPAN site by getting the file
       /pub/languages/perl/CPAN/MIRRORS from ftp://ftp.funet.fi . Alternatively, you can point
       your Web browser at http://www.perl.com and use its CPAN multiplex service. Within CPAN
       you find the latest released version of PDL in the directory CPAN/modules/by-module/PDL/.
       Another site that has the latest PDL distribution is http://pdl.perl.org . Thanks to the
       efforts of Frossie ( frossie@jach.hawaii.edu ) there is now a mirror site in the US at
       http://www.jach.hawaii.edu/~frossie/pdl-mirror/

       Q: 2.8	 What do I have to pay to get PDL?

       We are delighted to be able to give you the nicest possible answer on a question like
       this: PDL is *free software* and all sources are publicly available. But still, there are
       some copyrights to comply with. So please, try to be as nice as we (the PDL authors) are
       and try to comply with them.

       Oh, before you think it is *completely* free: you have to invest some time to pull the
       distribution from the net, compile and install it and (maybe) read the manuals.

GETTING HELP/MORE INFORMATION
       Q: 3.1	 Where can I get information on PDL?

       The complete PDL documentation is available with the PDL distribution.  If you have PDL
       installed on your machine and are on a unix like system then you can read the PDL manuals
       with the " man" command.  " man PDL::Intro" will lead the way to other PDL manual pages.
       In any case (i.e. also on non-unixes) " perldoc PDL::Intro" should work.

       The easiest way by far, however, to get familiar with PDL is to use the PDL online help
       facility from within the " perldl" shell. Just type " perldl" at your system prompt. Once
       you are inside the " perldl" shell type " help" .  Using the " help" and " apropos" com-
       mands inside the shell you should be able to find the way round the documentation. Even
       better, you can immediately try your newly acquired knowledge about PDL by issuing
       PDL/perl commands directly at the command line. To illustrate this process, here is the
       record of a typical perldl session of a PDL beginner (lengthy output is only symbolically
       reproduced in braces ( < ... ...  > )):

	       unix> perldl
	       perldl> help
	       <.... help output ....>
	       perldl> help PDL::Impatient
	       <.... man page ....>
	       perldl> $a = pdl (1,5,7.3,1.0)
	       perldl> $b = sequence float, 4, 4
	       perldl> help inner
	       <.... help on the 'inner' function ....>
	       perldl> $c = inner $a, $b
	       perldl> p $c
	       [22.6 79.8 137 194.2]

       For further sources of information that are accessible through the internet see next ques-
       tion.

       Q: 3.2	 Are there other PDL information sources on the internet?

       First of all, for all purely Perl-related questions there are tons of sources on the net.
       A good point to start is http://www.perl.com .

       The PDL home site can be accessed by pointing your web browser to http://pdl.perl.org . It
       has tons of goodies for anyone interested in PDL:

       o   PDL distributions

       o   Online documentation

       o   Pointers to an HTML archive of the PDL mailing lists

       o   A list of platforms on which PDL has been successfully tested.

       o   News about recently added features, ported libraries, etc.

       o   Name of the current pumpkin holders for the different PDL modules (if you want to know
	   what that means you better had a look at the web pages).

       Thanks to the efforts of Frossie ( frossie@jach.hawaii.edu ) there is now a mirror site in
       the US at http://www.jach.hawaii.edu/~frossie/pdl-mirror/ If you are interested in PDL in
       general you can join the PDL mailing list perldl@jach.hawaii.edu . This is a forum to dis-
       cuss programming issues in PDL, report bugs, seek assistance with PDL related problems,
       etc. To subscribe, send a message to perldl-request@jach.hawaii.edu containing a string in
       the following format:

	       subscribe me@my.email.address

       where you should replace the string  me@my.email.address with your email address. Past
       messages can be retrieved in digest format by anonymous ftp from
       ftp://ftp.jach.hawaii.edu/pub/ukirt/frossie/pdlp/ .  A searchable archive and a hypertext
       version of the traffic on this list can be found at http://www.xray.mpe.mpg.de/mail-
       ing-lists/perldl/ .

       If you are interested in all the technical details of the ongoing PDL development you can
       join the PDL developers mailing list pdl-porters@jach.hawaii.edu . To subscribe, send a
       message to pdl-porters-request@jach.hawaii.edu containing a string in the following for-
       mat:

	       subscribe me@my.email.address

       where you should replace the string  me@my.email.address with your email address. Past
       messages can be retrieved in digest format by anonymous ftp from
       ftp://ftp.jach.hawaii.edu/pub/ukirt/frossie/pdlp/ .  A searchable archive and a hypertext
       version of the traffic on this list can be found at http://www.xray.mpe.mpg.de/mail-
       ing-lists/pdl-porters/ .

       Crossposting between these lists should be avoided unless there is a  very good reason for
       doing that.

       Q: 3.3	 What is the current version of PDL ?

       As of this writing (FAQ version 0.6 of 01/06/2000 ) the latest released version is 2.006 .
       The latest versions should always be available from a CPAN mirror site near you (see above
       for info on where to get PDL).

       The most current version of PDL can be obtained from the CVS repository see ""CVS avail-
       ability of PDL"" below.

       Q: 3.4	 I want to contribute to the further development of PDL. How can I help?

       If you have a certain project in mind you should check if somebody else is already working
       on it or if you could benefit from existing modules. Do so by posting your planned project
       to the PDL developers mailing list at pdl-porters@jach.hawaii.edu . To subscribe, send a
       message to pdl-porters-request@jach.hawaii.edu containing a string in the following for-
       mat:

	       subscribe me@my.email.address

       where you should replace the string  me@my.email.address with your email address.  You can
       also read past and current mails in the searchable hypertext version of the mailing list
       at http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/ . We are always looking for peo-
       ple to write code and/or documentation ;).

       Q: 3.5	 I think I have found a bug in the current version of PDL. What shall I do?

       First, make sure that the bug/problem you came across has not already been dealt with
       somewhere else in this FAQ. Secondly, you can check the searchable archive of the PDL
       mailing list at	whether this bug has already been discussed. If you still haven't found
       any explanations you can post a bug report to perldl@jach.hawaii.edu .

INSTALLATION
       Q: 4.1	 I have problems installing PDL. What shall I do?

       First make sure you have read the file INSTALL in the distribution.  This contains a list
       of common problems which are unnecessary to repeat here. Next, check the file perldl.conf
       to see if by editing the configuration options in that file you will be able to success-
       fully build PDL. Some of the modules need additional software installed, please refer to
       the file DEPENDENCIES for further details. Make sure to edit the location of these pack-
       ages in perldl.conf if you have them in non-standard locations.

       If you would like to save an edited perldl.conf for future builds just copy it as
       ~/.perldl.conf into your home directory where it will be picked up automatically during
       the PDL build process.

       If you still can't make it work properly please submit a bug report including detailed
       information on the problems you encountered to the perldl mailing list (
       perldl@jach.hawaii.edu , see also above). Response is often rapid.

       Q: 4.2	 Are there configuration files for PDL I have to edit?

       Most users should not have to edit any configuration files manually.  However, in some
       cases you might have to supply some information about akwardly placed include
       files/libraries or you might want to explicitly disable building some of the optional PDL
       modules.  Check the files INSTALL and perldl.conf for details.

       If you had to manually edit perldl.conf and are happy with the results you can keep the
       file handy for future reference. Place it in ~/.perldl.conf where it will be picked up
       automatically or use " perl Makefile.PL	PDLCONF=your_file_name" next time you build PDL.

       Q: 4.3	 Do I need other software for successfull operation?

       For the basic PDL functionality you don't need any additional software.	However, some of
       the optional PDL modules included in the distribution (notably most graphics and some I/O
       modules) require certain other libraries/programs to be installed. Check the file DEPEN-
       DENCIES in the distribution for details and directions on how to get these.

       Q: 4.4	PDL compilation ends with " Error:  PL_na not declared"  or similar

       You have probably upgraded perl to 5.6 and tried to recompile an old version of PDL. The
       solution to this problem is to upgrade to a version ( > 2.005) which should have this
       fixed.

       If the latest version of PDL does not fix this problem for you, and you have made sure
       your old installation is not interfering, you should post a message to the mailing-list.

BINARY DISTRIBUTIONS
       Q: 4.5	 What binary distributions are available?

       Information about binary distributions of PDL can be found on http://pdl.perl.org .  At
       present there are binary distributions of PDL for Linux (RedHat and Debian), FreeBSD and
       Windows. If someone is interested in providing binary distributions for other architec-
       tures, that would be very welcome. Let us know on the pdl-porters@jach.hawaii.edu mailing
       list.

       Q: 4.6	 Does PDL run on Linux? (And what about packages?)

       Yes, PDL does run on Linux and indeed much of the development has been done under Linux.
       On http://pdl.perl.org you can find links to Debian packages, as well as the more actively
       updated RedHat packages. These should also work with Mandrake, and can possibly be con-
       verted to Debian using " alien" .

       Q: 4.7	 Does PDL run under Windows?

       To some extent is probably the fairest answer. There is no official effort to port PDL to
       Windows with each release of the software, and a volunteering effort would be much appre-
       ciated. However a port of ( 2.001 ) does already exist thanks to Christian Soeller.  A
       main worry on Windows platforms is the lack of a good graphics interface, any help with
       this would be very welcome.

       It is also important to note that there is no distribution of PDL through ActiveState's
       ppm. Such a compilation would be very welcome!

CVS AND ON-GOING DEVELOPMENT
       Q: 4.8	 Can I get PDL via CVS?

       Yes, as of December 1999, PDL is available at the CVS repository on http://www.source-
       forge.net . The tree is updated by developers who have accounts on Sourceforge and snap-
       shots of the tree are released regularly by the pumpkin holder (the pumpking).

       If you wish to access the CVS repository and install PDL from there all you need are two
       simple commands, however make sure you read some of the documentation on Sourceforge as
       well for full information, but the basic command is:

	   cvs -d:pserver:anonymous@cvs.PDL.sourceforge.net:/cvsroot/PDL login
	   cvs -z3 -d:pserver:anonymous@cvs.PDL.sourceforge.net:/cvsroot/PDL co PDL

       When prompted for a password just press the Enter key.  Note however that the CVS tree is
       to be considered a development release and as such you are very welcome to try it out, but
       it is not recommended for mission critical use and might crash unexpectedly.

       Q: 4.9  I had a problem with the CVS version, how do I check if	someone has submitted a
       patch?

       The Sourceforge system contains a patch-manager which contains patches that have not yet
       been applied to the distribution. This can be accessed by first accessing the Sourceforge
       web site and search for PDL. This will show you the project page for PDL and will give you
       access to the Patch manager.

       In addition, if you are not subscribing to the mailinglist, check the archive of the "
       pdl-porters" and " perldl" mailing lists.

       Q: 4.10	  I have gotten developer access to CVS, but I have trouble  committing uploads.

       The first you should do is to read the Sourceforge documentation and learn the basics
       about CVS. But assuming you know this here is a quick intro from Karl Glazebrook:

	  Delete your entire CVS directory structure and START AGAIN
	  (there is state)

	  In a clean directory:

	  setenv CVS_RSH	  ssh
	  setenv CVSROOT	  kgb@cvs.PDL.sourceforge.net:/cvsroot/PDL

	  cvs co PDL

	  You will need to type your password. every time you issue a cvs
	  command. there is no way around this if you use non-anon
	  access and you can't mix the two.

	  Howevery cvs committs will now work and write back to the server.

	  You will continue to have to type your password until you upload
	  a key to the sourcefourve web page. Once you have done this it
	  becomes painless.

PDL JARGON
       Q: 5.1	 What is threading (is PDL a newsreader) ?

       Unfortunately, in the context of PDL the term threading can have two different (but
       related) meanings:

       o   When mentioned in the INSTALL directions and possible during the build process we have
	   the usual computer science meaning of multithreading in mind (useful mainly on multi-
	   processor machines or clusters)

       o   PDL threading of operations on piddles (as mentioned in the indexing docs) is the
	   iteration of a basic operation over appropriate subslices of piddles, e.g. the inner
	   product " inner $a, $b" of a (3) pdl  $a and a (3,5,4) pdl  $b results in a (5,4) pid-
	   dle where each value is the result of an inner product of the (3) pdl with a (3) sub-
	   slice of the (3,5,4) piddle.  For details check "PDL::Indexing"

       PDL threading leads naturally to potentially parallel code which can make use of multi-
       threading on multiprocessor machines/networks; there you have the connection between the
       two types of use of the term.

       Q: 5.2	 What is a piddle " (;)"  ?

       Well, PDL scalar variables (which are instances of a particular class of perl objects,
       i.e. blessed thingies (see "man perlobj" )) are in common PDL parlance often called  pid-
       dles (for example, check the mailing list archives). Err, clear? If not, simply use the
       term  piddle when you refer to a PDL variable (an instance of a PDL object as you might
       remember) regardless of what actual data the PDL variable contains.

TECHNICAL QUESTIONS
       Q: 6.1	 What is perldl?

       Sometimes perldl is used as a synonym for PDL. Strictly speaking, however, the name perldl
       is reserved for the little shell that comes with the PDL distribution and is supposed to
       be used for the interactive prototyping of PDL scripts. For details check the perldl man
       page.

       Q: 6.2	 How do I get online help for PDL?

       Just type " help" (shortcut = "?") at the " perldl" prompt and proceed from there. Another
       useful command is the " apropos" (shortcut = "??") command.

       Also try the " demo" command in the perldl shell if you are new to PDL.

MANIPULATION OF PIDDLES
       Q: 6.3	 I want to access the third element of a pdl but $a[2] doesn't work ?!

       See answer to the next question why the normal perl array syntax doesn't work for pdls.

       Q: 6.4	 The docs say pdls are some kind of array. But why doesn't the perl array syntax
       work with pdls then ?

       Ok, you are right in a way. The docs say that pdls can be thought of arrays.  More specif-
       ically, it says ( "PDL::Impatient" ):

		   I find when using perlDL it is most useful to think of
		   standard perl @x variables as "lists" of generic
		   "things" and PDL variables like $x as
		   "arrays" which can be contained in lists or
		   hashes.

       So, while pdls can be thought of as some kind of multi-dimensional array they are  not
       arrays in the perl sense. Rather, from the point of view of perl they are some special
       class (which is currently implemented as an opaque pointer to some stuff in memory) and
       therefore need special functions (or 'methods' if you are using the OO version) to access
       individual elements or a range of elements. The functions/methods to check are " at" / "
       set" (see "the section 'Sections' in PDL::Impatient" ) or the powerful " slice" function
       and friends (see "PDL::Slices" and "PDL::Indexing" ).

       Finally, to confuse you completely, you can have perl arrays of plds, e.g. $spec[3] can
       refer to a pdl representing ,e.g, a spectrum, where $spec[3] is the fourth element of the
       perl list (or array ;)  @spec .	This may be confusing but is very useful !

       Q: 6.5	 How do I concatenate piddles?

       Most people will try to form new piddles from old piddles using some variation over the
       theme: " $a =  pdl([$b, 0, 2])" , but this does not work. The way to concatenate piddles
       is to use the function " cat" . Similarly you can split piddles using the command " dog" .

       Q: 6.6	 Sometimes I am getting these strange results when using inplace  operations?

       This question is related to the " inplace" function. From the documentation (see
       "PDL::Impatient" manpage):

		Most functions, e.g. log(), return a result which is
		a transformation of their argument. This makes for
		good programming practice. However many operations can
		be done "in-place" and this may be required when large
		arrays are in use and memory is at a premium. For these
		circumstances the operator inplace() is provided which
		prevents the extra copy and allows the argument to be
		modified. e.g.:

		$x = log($array);	   # $array unaffected
		log( inplace($bigarray) ); # $bigarray changed in situ

       And also from the doc !!:

		Obviously when used with some functions which can
		not be applied in situ (e.g. convolve()) unexpected
		effects may occur!

       Check the list of PDL functions at the end of PDL.pod which points out " inplace" -safe
       functions.

       Q: 6.7	 What is this strange usage of the string concatenation operator  " .="  in PDL
       scripts?

       See next question on assignment in PDL.

       Q: 6.8	 Why are there two different kinds of assignment in PDL ?

       This is caused by the fact that currently the assignment operator " =" allows only
       restricted overloading. For some purposes of PDL it turned out to be necessary to have
       more control over the overloading of an assignment operator. Therefore, PDL peruses the
       operator " .=" for certain types of assignments.

       Q: 6.9	 How do I set a set of values in a piddle?

       With versions of Perl prior to 5.6 this has to be done using a temporary variable.

		   perldl> $a = sequence(5); p $a
		      [0 1 2 3 4]
		   perldl> $tmp = $a->slice('1:2'); p $tmp;
		      [1 2]
		      perldl> $tmp .= pdl([5, 6]);    # Note .= !!
		   perldl> p $a
		      [0 5 6 3 4]

       This can also be made into one expression, which is often seen in PDL code:

		   perldl> ($tmp = $a->slice('1:2')) .= pdl([5,6])
		   perldl> p $a
		      [0 5 6 3 4]

       In Perl 5.6 this assignment can be simplified using lvalue subroutines, and this will be
       incorporated into PDL when 5.6 is more widespread.

       Q: 6.10	  Can I use a piddle in a conditional expression?

       Yes you can, but not in the way you probably tried first. It is not possible to use a pid-
       dle directly in a conditional expression since this is usually poorly defined. Instead PDL
       has two very useful functions: " any" and " all" . Use these to test if any or all ele-
       ments in a piddle fulfils some criterion:

	  perldl> $a=pdl ( 1, -2, 3);
	  perldl> print '$a has at least one element < 0' if (any $a < 0);
	  $a has at least one element < 0

	  perldl> print '$a is not positive definite' unless (all $a > 0);
	  $a is not positive definite

       Q: 6.11	  Logical operators and piddles -  '||' and ' & & ' doesn't work!

       It is a common problem that you try to make a mask array or something similar using a con-
       struct such as

		$mask = which($piddle > 1 && $piddle < 2);

       This  does not work! What you are looking for is the  bitwise logical operators '|' and '
       & ' which work on an element-by-element basis. So it is really very simple: Do not use
       logial operators on multi-element piddles since that really doesn't make sense, instead
       write the example as:

		$mask = which($piddle > 1 & $piddle < 2);

       which works correctly.

ADVANCED TOPICS
       Q: 6.12	  What is a null pdl ?

       " null" is a special token for 'empty piddle'. A null pdl can be used to flag to a PDL
       function that it should create an appropriately sized and typed piddle.	 Null piddles can
       be used in places where a PDL function expects an  output or  temporary argument.   Output
       and  temporary arguments are flagged in the  signature of a PDL function with the " [o]"
       and " [t]" qualifiers (see next question if you don't know what the  signature of a PDL
       function is).  For example, you can invoke the " sumover" function as follows:

		sumover $a, $b=null;

       which is equivalent to

		$b = sumover $a;

       If this seems still a bit murky check "PDL:Indexing" and "PDL::PP" for details about call-
       ing conventions, the  signature and  threading (see also below).

       Q: 6.13	  What is the signature of a PDL function ?

       The  signature of a function is an important concept in PDL.  Many (but not all) PDL func-
       tion have a  signature which specifies the arguments and their (minimal) dimensionality.
       As an example, look at the signature of the " maximum" function:

		'a(n); [o] b;'

       this says that " maximum" takes two arguments, the first of which is (at least) one-dimen-
       sional while the second one is zero-dimensional and an  output argument (flagged by the "
       [o]" qualifier). If the function is called with pdls of higher dimension the function will
       be repeatedly called with slices of these pdls of appropriate dimension(this is called
       threading in PDL).

       For details and further explanations consult "PDL::Indexing" and "PDL::PP" .

       Q: 6.14	  How can I subclass (inherit from) piddles?

       The short answer is: read "PDL::Objects" (e.g. type " help PDL::Objects" in the	perldl
       shell).

       The longer answer (extracted from "PDL::Objects" ): Since a PDL object is an opaque refer-
       ence to a C struct, it is not possible to extend the PDL class by e.g. extra data via sub-
       classing (as you could do with a hash based perl object).  To circumvent this problem PDL
       has built-in support to extent the PDL class via the  has-a relation for blessed hashes.
       You can get the	HAS-A behave like  IS-A simply in that you assign the PDL object to the
       attribute named " PDL" and redefine the method initialize(). For example:

		package FOO;

		@FOO::ISA = qw(PDL);
		sub initialize {
		my $class = shift;
		my $self = {
		creation_time => time(),  # necessary extension :-)
		PDL => PDL->null,	  # used to store PDL object
		};
		bless $self, $class;
		}

       For another example check the script t/subclass.t in the PDL distribution.

       Q: 6.15	  What on earth is this dataflow stuff ?

       Dataflow is an experimental project that you don't need to concern yourself with (it
       should not interfere with your usual programming).  However, if you want to know, have a
       look at "PDL::Dataflow" . There are applications which will benefit from this feature (and
       it is already at work behind the scenes).

       Q: 6.16	  What is PDL::PP?

       Simple answer: PDL::PP is both a glue between external libraries and PDL and a concise
       language for writing PDL functions.

       Slightly longer answer: PDL::PP is used to compile very concise definitions into XSUB rou-
       tines implemented in C that can easily be called from PDL and which automatically support
       threading, dataflow and other things without you having to worry about it.

       For further details check "PDL::PP" and the section on "Extensions of PDL".

       Q: 6.17	  What happens when I have several references to the same PDL object in different
       variables (cloning, etc?) ?

       Piddles behave like perl references in many respects. So when you say

		$a = pdl [0,1,2,3];
		$b = $a;

       then both $b and $a point to the same object, e.g. then saying

		$b++;

       will *not* create a copy of the original piddle but just increment in place, of which you
       can convince yourself by saying

		print $a;
		[1 2 3 4]

       This should not be mistaken for dataflow which connects several *different* objects so
       that data changes are propagated between the so linked piddles (though, under certain cir-
       cumstances, dataflown piddles can share physically the same data).

       It is important to keep the " reference nature " of piddles in mind when passing piddles
       into subroutines. If you modify the input pdls you modify the original argument,  not a
       copy of it. This is different from some other array processing languages but makes for
       very efficient passing of piddles between subroutines. If you do not want to modify the
       original argument but rather a copy of it just create a copy explicitly (this example also
       demonstrates how to properly check for an  explicit request to process inplace, assuming
       your routine can work inplace):

		sub myfunc {
		my $pdl = shift;
		if ($pdl->is_inplace)
		{$pdl->set_inplace(0)}
		else  # modify a copy by default
		{$pdl = $pdl->copy}
		$pdl->set(0,0);
		return $pdl;
		}

MISCELLANEOUS
       Q: 6.18	  What I/O formats are supported by PDL ?

       The current versions of PDL already support quite a number of different I/O formats. How-
       ever, it is not always obvious which module implements which formats. To help you find the
       right module for the format you require, here is a short list of the current list of I/O
       formats and a hint in which module to find the implementation:

       o   A home brew fast raw (binary) I/O format for PDL is implemented by the FastRaw module

       o   The FlexRaw module implements generic methods for the input and output of `raw' data
	   arrays.  In particular, it is designed to read output from FORTRAN 77 UNFORMATTED
	   files and the low-level C write function, even if the files are compressed or gzipped.

	   It is possible that the FastRaw functionality will be included in the FlexRaw module
	   at some time in the future.

       o   FITS I/O is implemented by the wfits/rfits functions in PDL::IO::Misc.

       o   Ascii file I/O in various formats can be achieved by using the " rcols" and " rgrep"
	   functions, also in PDL::IO::Misc.

       o   PDL::IO::Pic implements an interface to the netpbm/pbm+ filters to read/write several
	   popular image formats; also supported is output of image sequences as MPEG movies.

       o   On CPAN you can find the PDL-NetCDF module that works with the current released ver-
	   sion of PDL 2.004.

       For further details consult the documentation in the individual modules.

       Q: 6.19	  How can I stack a set of 2D arrays (images) into a 3D piddle?

       Assuming all arrays are of the same size and in some format recognised by rpic (see
       "PDL::IO::Pic" ) you could say:

		use PDL::IO::Pic;
		@names = qw/name1.tif .... nameN.tif/;	# some file names
		$dummy = PDL->rpic($names[0]);
		$cube = PDL->zeroes($dummy->type,$dummy->dims,$#names+1); # make 3D piddle
		for (0..$#names)
		{($tmp = $cube->slice(":,:,($_)")) .= PDL->rpic($names[$_])}

       The for loop reads the actual images into a temporary 2D piddle whose values are then
       assigned (using the overloaded " .=" operator) to the approriate slices of the 3D piddle
       $cube .

       Q: 6.20	  Where are testfiles for the graphics modules?

       This answer applies mainly to PDL::Graphics::TriD (PDL's device independent 3D graphics
       model) which is the trickiest one in this respect. You find some test scripts in
       Demos/TriD in the distribution. After you have built PDL just change to that directory and
       try

		perl -Mblib <testfile>

       where " < testfile "> ; should match the pattern " test[0-9].p" and watch the results.
       Some of the tests should bring up a window where you can control (twiddle) the 3D objects
       with the mouse. Try using MB1 for turning the objects in 3D space and MB3 to zoom in and
       out.

       If you have a VRML viewer plugin for netscape you can also try " tvrml*.p" for PDL gener-
       ated dynamic VRML.

       Some demos of 3D graphics with PDL can also be invoked using the " demo" command within
       the perldl shell.

       Q: 6.21	  What is TriD or PDL::TriD or PDL::Graphics::TriD?

       Questions like this should be a thing of the past with the PDL online help system in
       place. Just try (after installation):

		un*x> perldl
		perldl> apropos trid

       Check the output for promising hits and then try to look up some of them, e.g.

		perldl> help PDL::Graphics::TriD

       Note that case matters with " help" but not with " apropos" .

EXTENSIONS OF PDL
       Q: 7.1	 I am looking for a package to do XXX in PDL. Where shall I look for it?

       The first stop is again " perldl" or the PDL documentation. There is already a lot of
       functionality in PDL which you might be aware of. The easiest way to look for functional-
       ity is to use the " apropos" command:

		 perldl> apropos 'integral'
		 ceil		 Round to integral values in floating-point format
		 floor		 Round to integral values in floating-point format
		 intover	 Project via integral to N-1 dimensions
		 rint		 Round to integral values in floating-point format

       Since the apropos command is no sophisticated search engine make sure that you search on a
       couple of related topics and use short phrases.

       However there is a good chance that what you need is not part of the PDL distribution. You
       are then well advised to check out http://pdl.perl.org where there is a list of packages
       using PDL. If that does not solve your problem, ask on the mailing-list, if nothing else
       you might get assistance which will let you interface your package with PDL yourself, see
       also the next question.

       Q: 7.2	Can I access my C/Fortran library routines in  PDL?

       Yes, you can, in fact it is very simple for many simple applications. What you want is the
       PDL pre-prosessor PP ( "PDL::PP" ). This will allow you to make a simple interface to your
       C routine.

       The two functions you need to learn (at least first) are " pp_def" which defines the call-
       ing interface to the function, specifying input and output parameters, and contains the
       code that links to the external library. The other command is " pp_end" which finishes the
       PP definitions.	For details see the "PDL::PP" man-page, but we also have a worked example
       here.

	  double eight_sum(int n)
	  {
	       int i;
	       double sum, x;

	       sum = 0.0; x=0.0;
	       for (i=1; i<=n; i++) {
		 x++;
		 sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
	       }
	       return 1.0/sum;
	  }

       We will here show you an example of how you interface C code with PDL. This is the first
       example and will show you how to approximate the number 8...

       The C code is shown above and is a simple function returning a double, and expecting an
       integer - the number of terms in the sum - as input. This function could be defined in a
       library or, as we do here, as an inline function.

       We will postpone the writing of the Makefile till later. First we will construct the "
       .pd" file. This is the file containing PDL::PP code. We call this " eight.pd" .

	  #
	  # pp_def defines a PDL function.
	  #
	  pp_addhdr (
	  '
	  double eight_sum(int n)
	  {
	    int i;
	    double sum, x;

	    sum = 0.0; x=0.0;
	    for (i=1; i<=n; i++) {
	      x++;
	      sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
	     }
	    return 1.0/sum;

	  }
	  ');

	  pp_def (
		  'eight',
	       Pars => 'int a(); double [o]b();',
		  Code => '$b()=eight_sum($a());'
		 );

	  # Always make sure that you finish your PP declarations with
	  # pp_done

	  pp_done();

       A peculiarity with our example is that we have included the entire code with " pp_addhdr"
       instead of linking it in. This is only for the purposes of example, in a typical applica-
       tion you will use " pp_addhdr" to include header files. Note that the argument to "
       pp_addhdr" is enclosed in quotes.

       What is most important in this example is however the " pp_def" command. The first argu-
       ment to this is the name of the new function  eight  , then comes a hash which the real
       meat:

       o   This gives the input parameters (here " a" ) and the output parameters (here " b" ).
	   The latter are indicated by the " [o]" specifier. Both arguments can have a type spec-
	   ification as shown here.

	   Many variations and further flexibility in the interface can be specified. See the
	   manpage for details.

       o   This switch contains the code that should be executed. As you can see this is a rather
	   peculiar mix of C and Perl, but essentially it is just as you would write it in C, but
	   the variables that are passed from PDL are treated differently and have to be referred
	   to with a preceding '$'.

	   There are also simple macros to pass pointers to data and to obtain the values of
	   other Perl quantities, see the manual page for further details.

       Finally note the call to " pp_done()" at the end of the file. This is necessary in all PP
       files.

       Ok. So now we have a file with code that we dearly would like to use in Perl via PDL. To
       do this we need to compile the function, and to do that we need a Makefile.

	  use PDL::Core::Dev;
	  use ExtUtils::MakeMaker;
	  PDL::Core::Dev->import();

	  $package = ["eight.pd",Eight,PDL::Eight];
	  %hash = pdlpp_stdargs($package);

	  WriteMakefile( %hash );

	  sub MY::postamble {pdlpp_postamble($package)};

       The code above should go in a file called Makefile.PL, which should subsequently be called
       in  the standard Perl way: " perl Makefile.PL" .  This should give you a Makefile and run-
       ning " make" should compile the module for you and " make install" will install it for
       you.

       Q: 7.3	 How can I interface package XXX in PDL?

       This question is closely related to the previous one, and as we said there, the "PDL::PP"
       pre-processor is the standard way of interfacing external packages with PDL. The most
       usual way to use PDL::PP is to write a short interface routine, see the "PDL::PP" manpage
       and the answer to the previous question for examples.

       However it is also possible to interface a package to PLD by re-writing your function in
       PDL::PP directly. This can be convenient in certain situations, in particular if you have
       a routine that expects a function as input and you would like to pass the function a Perl
       function for convenience.

       The "PDL::PP" manpage is the main source of information for writing PDL::PP extensions,
       but it is very useful to look for files in the distribution of PDL as many of the core
       functions are written in PDL::PP. Look for files that end in " .pd" which is the generally
       accepted suffix for PDL::PP files. But we also have a simple example here

       The following example will show you how to write a simple function that automatically
       allows threading. To make this concise the example is of an almost trivial function, but
       the intention is to show the basics of writing a PDL::PP interface.

       We will write a simple function that calculates the minimum, maximum and average of a pid-
       dle. On my machine the resulting function is 8 times faster than the built-in function "
       stats" (of course the latter also calculates the median).

       Let's jump straight in. Here is the code (from a file called " quickstats.pd" )

	  #
	  pp_def('quickstats',
	       Pars => 'a(n); [o]avg(); [o]max(); [o]min()',
	       Code => '$GENERIC(a) curmax, curmin;
			$GENERIC(a) tmp=0;
			   loop(n) %{
			     tmp += $a();
			     if (!n || $a() > curmax) { curmax = $a();}
			     if (!n || $a() < curmin) { curmin = $a();}
			   %}
			   $avg() = tmp/$SIZE(n);
			$max() = curmax;
			$min() = curmin;
			  '
	       );

	  pp_done();

       The above might look like a confusing mixture of C and Perl, but behind the peculiar syn-
       tax lies a very powerful language. Let us take it line by line.

       The first line declares that we are starting the definition of a PDL:PP function called "
       quickstats" .

       The second line is very important as it specifies the input and output parameters of the
       function.   a(n) tells us that there is one input parameter that we will refer to as " a"
       which is expected to be a vector of length n (likewise matrices, both square and rectangu-
       lar would be written as " a(n,n)" and " a(n,m)" respectively). To indicate that something
       is an output parameter we put " [o]" in front of their names, so referring back to the
       code we see that avg, max and min are three output parameters, all of which are scalar
       (since they have no dimensional size indicated.

       The third line starts the code definition which is essentially pure C but with a couple of
       convenient functions.   $GENERIC is a function that returns the C type of its argument -
       here the input parameter a. Thus the first two lines of the code section are variable dec-
       larations.

       The  loop(n) construct is a convenience function that loops over the dimension called n in
       the parameter section. Inside this loop we calculate the cumulative sum of the input vec-
       tor and keep track of the maximum and minimum values. Finally we assign the resulting val-
       ues to the output parameters.

       Finally we finish our function declaration with " pp_done()" .

       To compile our new function we need to create a Makefile, which we will just list since
       its creation is discussed in an earlier question.

	  use PDL::Core::Dev;
	  use ExtUtils::MakeMaker;
	  PDL::Core::Dev->import();

	  $package = ["quickstats.pd",Quickstats,PDL::Quickstats];
	  %hash = pdlpp_stdargs($package);

	  WriteMakefile( %hash );

	  sub MY::postamble {pdlpp_postamble($package)};

       An example Makefile.PL

       Our new statistic function should now compile using the tried and tested perl way: " perl
       Makefile.PL; make" .

       You should experiment with this function, changing the calculations and input and output
       parameters. In conjunction with the PDL::PP manpage this should allow you to quickly write
       more advanced routines directly in PDL::PP.

THE WHO WHEN WHAT
CHANGES
       o
	   o   markers for alpha stage functionality removed

	   o   restructured description

	   o   development/support of PDL

	   o   PDL and online help

	   o   subclassing piddles

	   o   new INSTALLATION section

	   o   how to stack 2D piddles - > 3D piddle

	   o   questions regarding TriD

       o
	   o   use of perl5.004 is now required

	   o   PDL I/O formats

	   o   piddles behave like perl references

	   o   null PDL's and output arguments

	   o   signature

       o
	   o   questions about pdls and perl array syntax

	   o   added requirement for C compiler in answer to 'what machines...' question

	   o   PDL jargon section

	   o   piddles

       o
	   o   upgraded released/alpha version numbers

	   o   added another WYANDL reason

	   o   split into perldl/pdl-porters mailing lists

       o
	   o   initial revision

BUGS
       If you find any inaccuracies in this document (or disfunctional URLs) please report to the
       perldl mailing list perldl@jach.hawaii.edu or to the current FAQ maintainer Jarle Brinch-
       mann ( jarle@astro.ox.ac.uk ).

ACKNOWLEDGEMENTS
       Achim Bohnet ( ach@mpe.mpg.de ) for suggesting CoolHTML as a prettypodder (although we
       have switched to XML now) and various other improvements. Suggestions for some questions
       were taken from Perl Faq and adapted for PDL.

CONTRIBUTORS
       Many people have contributed or given feedback on the current version of the FAQ, here is
       an incomplete list of individuals whose contributions or posts to the mailing-list have
       improved this FAQ at some point in time alphabetically listed by first name: Christian
       Soeller, Doug Burke, Doug Hunt, Frank Schmauder, Jarle Brinchmann, John Cerney, Karl
       Glazebrook, Kurt Starsinic, Thomas Yengst, Tuomas J. Lukka.

AUTHOR AND COPYRIGHT
       This document emerged from a joint effort of several PDL developers (Karl Glazebrook (
       kgb@aaoepp.aao.gov.au ), Tuomas J. Lukka ( lukka@iki.fi ), Christian Soeller (
       c.soeller@auckland.ac.nz )) to compile a list of the most frequently asked questions about
       PDL with answers.  Permission is granted for verbatim copying (and formatting) of this
       material as part of PDL. Permission is explicitly not granted for distribution in book or
       any corresponding form. Email the current FAQ maintainer Jarle Brinchmann (
       jarle@astro.ox.ac.uk ) or ask on the PDL mailing list perldl@jach.hawaii.edu if some of
       the issues covered in here are unclear.

perl v5.8.0				    2000-06-02					   FAQ(1)


All times are GMT -4. The time now is 03:33 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password