Provided by: pdl_2.020-3_amd64 bug

NAME

       PDL::Scilab - A guide for Scilab users.

INTRODUCTION

       If you are a Scilab user, this page is for you. It explains the key differences between
       Scilab and PDL to help you get going as quickly as possible.

       This document is not a tutorial. For that, go to PDL::QuickStart. This document
       complements the Quick Start guide, as it highlights the key differences between Scilab and
       PDL.

Perl

       The key difference between Scilab and PDL is Perl.

       Perl is a general purpose programming language with thousands of modules freely available
       on the web. PDL is an extension of Perl. This gives PDL programs access to more features
       than most numerical tools can dream of.  At the same time, most syntax differences between
       Scilab and PDL are a result of its Perl foundation.

       You do not have to learn much Perl to be effective with PDL. But if you wish to learn
       Perl, there is excellent documentation available on-line (<http://perldoc.perl.org>) or
       through the command "perldoc perl".  There is also a beginner's portal
       (<http://perl-begin.org>).

       Perl's module repository is called CPAN (<http://www.cpan.org>) and it has a vast array of
       modules. Run "perldoc cpan" for more information.

TERMINOLOGY: PIDDLE

       Scilab typically refers to vectors, matrices, and arrays. Perl already has arrays, and the
       terms "vector" and "matrix" typically refer to one- and two-dimensional collections of
       data. Having no good term to describe their object, PDL developers coined the term
       "piddle" to give a name to their data type.

       A piddle consists of a series of numbers organized as an N-dimensional data set. Piddles
       provide efficient storage and fast computation of large N-dimensional matrices. They are
       highly optimized for numerical work.

       For more information, see "Piddles vs Perl Arrays" later in this document.

COMMAND WINDOW AND IDE

       PDL does not come with a dedicated IDE. It does however come with an interactive shell and
       you can use a Perl IDE to develop PDL programs.

   PDL interactive shell
       To start the interactive shell, open a terminal and run "perldl" or "pdl2".  As in Scilab,
       the interactive shell is the best way to learn the language. To exit the shell, type
       "exit", just like Scilab.

   Writing PDL programs
       One popular IDE for Perl is called Padre (<http://padre.perlide.org>).  It is cross
       platform and easy to use.

       Whenever you write a stand-alone PDL program (i.e. outside the "perldl" or "pdl2" shells)
       you must start the program with "use PDL;".  This command imports the PDL module into
       Perl. Here is a sample PDL program:

         use PDL;             # Import main PDL module.
         use PDL::NiceSlice;  # Import additional PDL module.

         $y = pdl [2,3,4];              # Statements end in semicolon.
         $A = pdl [ [1,2,3],[4,5,6] ];  # 2-dimensional piddle.

         print $A x $y->transpose;

       Save this file as "myprogram.pl" and run it with:

         perl myprogram.pl

   New: Flexible syntax
       In very recent versions of PDL (version 2.4.7 or later) there is a flexible matrix syntax
       that can look extremely similar to Scilab:

       1) Use a ';' to delimit rows:

         $y = pdl q[ 2,3,4 ];
         $A = pdl q[ 1,2,3 ; 4,5,6 ];

       2) Use spaces to separate elements:

         $y = pdl q[ 2 3 4 ];
         $A = pdl q[ 1 2 3 ; 4 5 6 ];

       Basically, as long as you put a "q" in front of the opening bracket, PDL should "do what
       you mean". So you can write in a syntax that is more comfortable for you.

A MODULE FOR SCILAB USERS

       Here is a module that Scilab users will want to use:

       PDL::NiceSlice
            Gives PDL a syntax for slices (sub-matrices) that is shorter and more familiar to
            Scilab users.

              // Scilab
              b(1:5)            -->  Selects the first 5 elements from b.

              # PDL without NiceSlice
              $y->slice("0:4")  -->  Selects the first 5 elements from $y.

              # PDL with NiceSlice
              $y(0:4)           -->  Selects the first 5 elements from $y.

BASIC FEATURES

       This section explains how PDL's syntax differs from Scilab. Most Scilab users will want to
       start here.

   General "gotchas"
       Indices
            In PDL, indices start at '0' (like C and Java), not 1 (like Scilab).  For example, if
            $y is an array with 5 elements, the elements would be numbered from 0 to 4.

       Displaying an object
            Scilab normally displays object contents automatically. In PDL you display objects
            explicitly with the "print" command or the shortcut "p":

            Scilab:

             --> a = 12
             a =  12.
             --> b = 23;       // Suppress output.
             -->

            PerlDL:

             pdl> $x = 12    # No output.
             pdl> print $x   # Print object.
             12
             pdl> p $x       # "p" is a shorthand for "print" in the shell.
             12

   Creating Piddles
       Variables in PDL
            Variables always start with the '$' sign.

             Scilab:    value  = 42
             PerlDL:    $value = 42

       Basic syntax
            Use the "pdl" constructor to create a new piddle.

             Scilab:    v  = [1,2,3,4]
             PerlDL:    $v = pdl [1,2,3,4]

             Scilab:    A  =      [ 1,2,3  ;  3,4,5 ]
             PerlDL:    $A = pdl [ [1,2,3] , [3,4,5] ]

       Simple matrices
                                  Scilab       PDL
                                  ------       ------
              Matrix of ones      ones(5,5)    ones 5,5
              Matrix of zeros     zeros(5,5)   zeros 5,5
              Random matrix       rand(5,5)    random 5,5
              Linear vector       1:5          sequence 5

            Notice that in PDL the parenthesis in a function call are often optional.  It is
            important to keep an eye out for possible ambiguities. For example:

              pdl> p zeros 2, 2 + 2

            Should this be interpreted as "zeros(2,2) + 2" or as "zeros 2, (2+2)"?  Both are
            valid statements:

              pdl> p zeros(2,2) + 2
              [
               [2 2]
               [2 2]
              ]
              pdl> p zeros 2, (2+2)
              [
               [0 0]
               [0 0]
               [0 0]
               [0 0]
              ]

            Rather than trying to memorize Perl's order of precedence, it is best to use
            parentheses to make your code unambiguous.

       Linearly spaced sequences
              Scilab:   --> linspace(2,10,5)
                        ans = 2.  4.  6.  8.  10.

              PerlDL:   pdl> p zeroes(5)->xlinvals(2,10)
                        [2 4 6 8 10]

            Explanation: Start with a 1-dimensional piddle of 5 elements and give it equally
            spaced values from 2 to 10.

            Scilab has a single function call for this. On the other hand, PDL's method is more
            flexible:

              pdl> p zeros(5,5)->xlinvals(2,10)
              [
               [ 2  4  6  8 10]
               [ 2  4  6  8 10]
               [ 2  4  6  8 10]
               [ 2  4  6  8 10]
               [ 2  4  6  8 10]
              ]
              pdl> p zeros(5,5)->ylinvals(2,10)
              [
               [ 2  2  2  2  2]
               [ 4  4  4  4  4]
               [ 6  6  6  6  6]
               [ 8  8  8  8  8]
               [10 10 10 10 10]
              ]
              pdl> p zeros(3,3,3)->zlinvals(2,6)
              [
               [
                [2 2 2]
                [2 2 2]
                [2 2 2]
               ]
               [
                [4 4 4]
                [4 4 4]
                [4 4 4]
               ]
               [
                [6 6 6]
                [6 6 6]
                [6 6 6]
               ]
              ]

       Slicing and indices
            Extracting a subset from a collection of data is known as slicing.  The PDL shell and
            Scilab have a similar syntax for slicing, but there are two important differences:

            1) PDL indices start at 0, as in C and Java. Scilab starts indices at 1.

            2) In Scilab you think "rows and columns". In PDL, think "x and y".

              Scilab                         PerlDL
              ------                         ------
              --> A                           pdl> p $A
              A =                            [
                   1.  2.  3.                 [1 2 3]
                   4.  5.  6.                 [4 5 6]
                   7.  8.  9.                 [7 8 9]
                                             ]
              -------------------------------------------------------
              (row = 2, col = 1)             (x = 0, y = 1)
              --> A(2,1)                      pdl> p $A(0,1)
              ans =                          [
                     4.                       [4]
                                             ]
              -------------------------------------------------------
              (row = 2 to 3, col = 1 to 2)   (x = 0 to 1, y = 1 to 2)
              --> A(2:3,1:2)                  pdl> p $A(0:1,1:2)
              ans =                          [
                     4.  5.                   [4 5]
                     7.  8.                   [7 8]
                                             ]

            Warning
                 When you write a stand-alone PDL program you have to include the PDL::NiceSlice
                 module. See the previous section "MODULES FOR SCILAB USERS" for more
                 information.

                   use PDL;             # Import main PDL module.
                   use PDL::NiceSlice;  # Nice syntax for slicing.

                   $A = random 4,4;
                   print $A(0,1);

   Matrix Operations
       Matrix multiplication
                  Scilab:    A * B
                  PerlDL:    $A x $B

       Element-wise multiplication
                  Scilab:    A .* B
                  PerlDL:    $A * $B

       Transpose
                  Scilab:    A'
                  PerlDL:    $A->transpose

   Functions that aggregate data
       Some functions (like "sum", "max" and "min") aggregate data for an N-dimensional data set.
       Scilab and PDL both give you the option to apply these functions to the entire data set or
       to just one dimension.

       Scilab    In Scilab, these functions work along the entire data set by default, and an
                 optional parameter "r" or "c" makes them act over rows or columns.

                   --> A = [ 1,5,4  ;  4,2,1 ]
                   A = 1.  5.  4.
                       4.  2.  1.
                   --> max(A)
                   ans = 5
                   --> max(A, "r")
                   ans = 4.    5.    4.
                   --> max(A, "c")
                   ans = 5.
                         4.

       PDL       PDL offers two functions for each feature.

                   sum   vs   sumover
                   avg   vs   average
                   max   vs   maximum
                   min   vs   minimum

                 The long name works over a dimension, while the short name works over the entire
                 piddle.

                   pdl> p $A = pdl [ [1,5,4] , [4,2,1] ]
                   [
                    [1 5 4]
                    [4 2 1]
                   ]
                   pdl> p $A->maximum
                   [5 4]
                   pdl> p $A->transpose->maximum
                   [4 5 4]
                   pdl> p $A->max
                   5

   Higher dimensional data sets
       A related issue is how Scilab and PDL understand data sets of higher dimension. Scilab was
       designed for 1D vectors and 2D matrices with higher dimensional objects added on top. In
       contrast, PDL was designed for N-dimensional piddles from the start. This leads to a few
       surprises in Scilab that don't occur in PDL:

       Scilab sees a vector as a 2D matrix.
              Scilab                       PerlDL
              ------                       ------
              --> vector = [1,2,3,4];       pdl> $vector = pdl [1,2,3,4]
              --> size(vector)              pdl> p $vector->dims
              ans = 1 4                    4

            Scilab sees "[1,2,3,4]" as a 2D matrix (1x4 matrix). PDL sees it as a 1D vector: A
            single dimension of size 4.

       But Scilab ignores the last dimension of a 4x1x1 matrix.
              Scilab                       PerlDL
              ------                       ------
              --> A = ones(4,1,1);          pdl> $A = ones 4,1,1
              --> size(A)                   pdl> p $A->dims
              ans = 4 1                    4 1 1

       And Scilab treats a 4x1x1 matrix differently from a 1x1x4 matrix.
              Scilab                       PerlDL
              ------                       ------
              --> A = ones(1,1,4);          pdl> $A = ones 1,1,4
              --> size(A)                   pdl> p $A->dims
              ans = 1 1 4                  1 1 4

       Scilab has no direct syntax for N-D arrays.
              pdl> $A = pdl [ [[1,2,3],[4,5,6]], [[2,3,4],[5,6,7]] ]
              pdl> p $A->dims
              3 2 2

       Feature support.
            In Scilab, several features are not available for N-D arrays. In PDL, just about any
            feature supported by 1D and 2D piddles, is equally supported by N-dimensional
            piddles. There is usually no distinction:

              Scilab                       PerlDL
              ------                       ------
              --> A = ones(3,3,3);         pdl> $A = ones(3,3,3);
              --> A'                       pdl> transpose $A
                  => ERROR                         => OK

   Loop Structures
       Perl has many loop structures, but we will only show the one that is most familiar to
       Scilab users:

         Scilab              PerlDL
         ------              ------
         for i = 1:10        for $i (1..10) {
             disp(i)             print $i
         end                 }

       Note Never use for-loops for numerical work. Perl's for-loops are faster than Scilab's,
            but they both pale against a "vectorized" operation.  PDL has many tools that
            facilitate writing vectorized programs.  These are beyond the scope of this guide. To
            learn more, see: PDL::Indexing, PDL::Threading, and PDL::PP.

            Likewise, never use 1..10 for numerical work, even outside a for-loop.  1..10 is a
            Perl array. Perl arrays are designed for flexibility, not speed. Use piddles instead.
            To learn more, see the next section.

   Piddles vs Perl Arrays
       It is important to note the difference between a Piddle and a Perl array. Perl has a
       general-purpose array object that can hold any type of element:

         @perl_array = 1..10;
         @perl_array = ( 12, "Hello" );
         @perl_array = ( 1, 2, 3, \@another_perl_array, sequence(5) );

       Perl arrays allow you to create powerful data structures (see Data structures below), but
       they are not designed for numerical work.  For that, use piddles:

         $pdl = pdl [ 1, 2, 3, 4 ];
         $pdl = sequence 10_000_000;
         $pdl = ones 600, 600;

       For example:

         $points =  pdl  1..10_000_000    # 4.7 seconds
         $points = sequence 10_000_000    # milliseconds

       TIP: You can use underscores in numbers ("10_000_000" reads better than 10000000).

   Conditionals
       Perl has many conditionals, but we will only show the one that is most familiar to Scilab
       users:

         Scilab                          PerlDL
         ------                          ------
         if value > MAX                  if ($value > $MAX) {
             disp("Too large")               print "Too large\n";
         elseif value < MIN              } elsif ($value < $MIN) {
             disp("Too small")               print "Too small\n";
         else                            } else {
             disp("Perfect!")                print "Perfect!\n";
         end                             }

       Note Here is a "gotcha":

              Scilab:  elseif
              PerlDL:  elsif

            If your conditional gives a syntax error, check that you wrote your "elsif"'s
            correctly.

   TIMTOWDI (There Is More Than One Way To Do It)
       One of the most interesting differences between PDL and other tools is the expressiveness
       of the Perl language. TIMTOWDI, or "There Is More Than One Way To Do It", is Perl's motto.

       Perl was written by a linguist, and one of its defining properties is that statements can
       be formulated in different ways to give the language a more natural feel. For example, you
       are unlikely to say to a friend:

        "While I am not finished, I will keep working."

       Human language is more flexible than that. Instead, you are more likely to say:

        "I will keep working until I am finished."

       Owing to its linguistic roots, Perl is the only programming language with this sort of
       flexibility. For example, Perl has traditional while-loops and if-statements:

         while ( ! finished() ) {
             keep_working();
         }

         if ( ! wife_angry() ) {
             kiss_wife();
         }

       But it also offers the alternative until and unless statements:

         until ( finished() ) {
             keep_working();
         }

         unless ( wife_angry() ) {
             kiss_wife();
         }

       And Perl allows you to write loops and conditionals in "postfix" form:

         keep_working() until finished();

         kiss_wife() unless wife_angry();

       In this way, Perl often allows you to write more natural, easy to understand code than is
       possible in more restrictive programming languages.

   Functions
       PDL's syntax for declaring functions differs significantly from Scilab's.

         Scilab                          PerlDL
         ------                          ------
         function retval = foo(x,y)      sub foo {
             retval = x.**2 + x.*y           my ($x, $y) = @_;
         endfunction                         return $x**2 + $x*$y;
                                         }

       Don't be intimidated by all the new syntax. Here is a quick run through a function
       declaration in PDL:

       1) "sub" stands for "subroutine".

       2) "my" declares variables to be local to the function.

       3) "@_" is a special Perl array that holds all the function parameters.  This might seem
       like a strange way to do functions, but it allows you to make functions that take a
       variable number of parameters. For example, the following function takes any number of
       parameters and adds them together:

         sub mysum {
             my ($i, $total) = (0, 0);
             for $i (@_) {
                 $total += $i;
             }
             return $total;
         }

       4) You can assign values to several variables at once using the syntax:

         ($x, $y, $z) = (1, 2, 3);

       So, in the previous examples:

         # This declares two local variables and initializes them to 0.
         my ($i, $total) = (0, 0);

         # This takes the first two elements of @_ and puts them in $x and $y.
         my ($x, $y) = @_;

       5) The "return" statement gives the return value of the function, if any.

ADDITIONAL FEATURES

   Data structures
       To create complex data structures, Scilab uses "lists" and "structs".  Perl's arrays and
       hashes offer similar functionality. This section is only a quick overview of what Perl has
       to offer. To learn more about this, please go to <http://perldoc.perl.org/perldata.html>
       or run the command "perldoc perldata".

       Arrays
            Perl arrays are similar to Scilab's lists. They are both a sequential data structure
            that can contain any data type.

              Scilab
              ------
              list( 1, 12, "hello", zeros(3,3) , list( 1, 2) );

              PerlDL
              ------
              @array = ( 1, 12, "hello" , zeros(3,3), [ 1, 2 ] )

            Notice that Perl array's start with the "@" prefix instead of the "$" used by
            piddles.

            To learn about Perl arrays, please go to <http://perldoc.perl.org/perldata.html> or
            run the command "perldoc perldata".

       Hashes
            Perl hashes are similar to Scilab's structure arrays:

              Scilab
              ------
              --> drink = struct('type', 'coke', 'size', 'large', 'myarray', ones(3,3,3))
              --> drink.type = 'sprite'
              --> drink.price = 12          // Add new field to structure array.

              PerlDL
              ------
              pdl> %drink = ( type => 'coke' , size => 'large', mypiddle => ones(3,3,3) )
              pdl> $drink{type} = 'sprite'
              pdl> $drink{price} = 12   # Add new field to hash.

            Notice that Perl hashes start with the "%" prefix instead of the "@" for arrays and
            "$" used by piddles.

            To learn about Perl hashes, please go to <http://perldoc.perl.org/perldata.html> or
            run the command "perldoc perldata".

   Performance
       PDL has powerful performance features, some of which are not normally available in
       numerical computation tools. The following pages will guide you through these features:

       PDL::Indexing
            Level: Beginner

            This beginner tutorial covers the standard "vectorization" feature that you already
            know from Scilab. Use this page to learn how to avoid for-loops to make your program
            more efficient.

       PDL::Threading
            Level: Intermediate

            PDL's "vectorization" feature goes beyond what most numerical software can do. In
            this tutorial you'll learn how to "thread" over higher dimensions, allowing you to
            vectorize your program further than is possible in Scilab.

       Benchmarks
            Level: Intermediate

            Perl comes with an easy to use benchmarks module to help you find how long it takes
            to execute different parts of your code. It is a great tool to help you focus your
            optimization efforts. You can read about it online
            (<http://perldoc.perl.org/Benchmark.html>) or through the command "perldoc
            Benchmark".

       PDL::PP
            Level: Advanced

            PDL's Pre-Processor is one of PDL's most powerful features. You write a function
            definition in special markup and the pre-processor generates real C code which can be
            compiled. With PDL:PP you get the full speed of native C code without having to deal
            with the full complexity of the C language.

   Plotting
       PDL has full-featured plotting abilities. Unlike Scilab, PDL relies more on third-party
       libraries (pgplot and PLplot) for its 2D plotting features.  Its 3D plotting and graphics
       uses OpenGL for performance and portability.  PDL has three main plotting modules:

       PDL::Graphics::PGPLOT
            Best for: Plotting 2D functions and data sets.

            This is an interface to the venerable PGPLOT library. PGPLOT has been widely used in
            the academic and scientific communities for many years. In part because of its age,
            PGPLOT has some limitations compared to newer packages such as PLplot (e.g. no RGB
            graphics).  But it has many features that still make it popular in the scientific
            community.

       PDL::Graphics::PLplot
            Best for: Plotting 2D functions as well as 2D and 3D data sets.

            This is an interface to the PLplot plotting library. PLplot is a modern, open source
            library for making scientific plots.  It supports plots of both 2D and 3D data sets.
            PLplot is best supported for unix/linux/macosx platforms. It has an active developers
            community and support for win32 platforms is improving.

       PDL::Graphics::TriD
            Best for: Plotting 3D functions.

            The native PDL 3D graphics library using OpenGL as a backend for 3D plots and data
            visualization. With OpenGL, it is easy to manipulate the resulting 3D objects with
            the mouse in real time.

   Writing GUIs
       Through Perl, PDL has access to all the major toolkits for creating a cross platform
       graphical user interface. One popular option is wxPerl (<http://wxperl.sourceforge.net>).
       These are the Perl bindings for wxWidgets, a powerful GUI toolkit for writing cross-
       platform applications.

       wxWidgets is designed to make your application look and feel like a native application in
       every platform. For example, the Perl IDE Padre is written with wxPerl.

   Xcos / Scicos
       Xcos (formerly Scicos) is a graphical dynamical system modeler and simulator. It is part
       of the standard Scilab distribution. PDL and Perl do not have a direct equivalent to
       Scilab's Xcos. If this feature is important to you, you should probably keep a copy of
       Scilab around for that.

COPYRIGHT

       Copyright 2010 Daniel Carrera (dcarrera@gmail.com). You can distribute and/or modify this
       document under the same terms as the current Perl license.

       See: http://dev.perl.org/licenses/