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

NAME

6       PDL::Scilab - A guide for Scilab users.
7

INTRODUCTION

9       If you are a Scilab user, this page is for you. It explains the key
10       differences between Scilab and PDL to help you get going as quickly as
11       possible.
12
13       This document is not a tutorial. For that, go to PDL::QuickStart. This
14       document complements the Quick Start guide, as it highlights the key
15       differences between Scilab and PDL.
16

Perl

18       The key difference between Scilab and PDL is Perl.
19
20       Perl is a general purpose programming language with thousands of
21       modules freely available on the web. PDL is an extension of Perl. This
22       gives PDL programs access to more features than most numerical tools
23       can dream of.  At the same time, most syntax differences between Scilab
24       and PDL are a result of its Perl foundation.
25
26       You do not have to learn much Perl to be effective with PDL. But if you
27       wish to learn Perl, there is excellent documentation available on-line
28       (<http://perldoc.perl.org>) or through the command "perldoc perl".
29       There is also a beginner's portal (<http://perl-begin.org>).
30
31       Perl's module repository is called CPAN (<http://www.cpan.org>) and it
32       has a vast array of modules. Run "perldoc cpan" for more information.
33

TERMINOLOGY: NDARRAY

35       Scilab typically refers to vectors, matrices, and arrays. Perl already
36       has arrays, and the terms "vector" and "matrix" typically refer to one-
37       and two-dimensional collections of data. Having no good term to
38       describe their object, PDL developers coined the term "ndarray" to give
39       a name to their data type.
40
41       An ndarray consists of a series of numbers organized as an
42       N-dimensional data set. ndarrays provide efficient storage and fast
43       computation of large N-dimensional matrices. They are highly optimized
44       for numerical work.
45
46       For more information, see "ndarrays vs Perl Arrays" later in this
47       document.
48

COMMAND WINDOW AND IDE

50       PDL does not come with a dedicated IDE. It does however come with an
51       interactive shell and you can use a Perl IDE to develop PDL programs.
52
53   PDL interactive shell
54       To start the interactive shell, open a terminal and run "perldl" or
55       "pdl2".  As in Scilab, the interactive shell is the best way to learn
56       the language. To exit the shell, type "exit", just like Scilab.
57
58   Writing PDL programs
59       One popular IDE for Perl is called Padre (<http://padre.perlide.org>).
60       It is cross platform and easy to use.
61
62       Whenever you write a stand-alone PDL program (i.e. outside the "perldl"
63       or "pdl2" shells) you must start the program with "use PDL;".  This
64       command imports the PDL module into Perl. Here is a sample PDL program:
65
66         use PDL;             # Import main PDL module.
67         use PDL::NiceSlice;  # Import additional PDL module.
68
69         $y = pdl [2,3,4];              # Statements end in semicolon.
70         $A = pdl [ [1,2,3],[4,5,6] ];  # 2-dimensional ndarray.
71
72         print $A x $y->transpose;
73
74       Save this file as "myprogram.pl" and run it with:
75
76         perl myprogram.pl
77
78   New: Flexible syntax
79       In very recent versions of PDL (version 2.4.7 or later) there is a
80       flexible matrix syntax that can look extremely similar to Scilab:
81
82       1) Use a ';' to delimit rows:
83
84         $y = pdl q[ 2,3,4 ];
85         $A = pdl q[ 1,2,3 ; 4,5,6 ];
86
87       2) Use spaces to separate elements:
88
89         $y = pdl q[ 2 3 4 ];
90         $A = pdl q[ 1 2 3 ; 4 5 6 ];
91
92       Basically, as long as you put a "q" in front of the opening bracket,
93       PDL should "do what you mean". So you can write in a syntax that is
94       more comfortable for you.
95

A MODULE FOR SCILAB USERS

97       Here is a module that Scilab users will want to use:
98
99       PDL::NiceSlice
100            Gives PDL a syntax for slices (sub-matrices) that is shorter and
101            more familiar to Scilab users.
102
103              // Scilab
104              b(1:5)            -->  Selects the first 5 elements from b.
105
106              # PDL without NiceSlice
107              $y->slice("0:4")  -->  Selects the first 5 elements from $y.
108
109              # PDL with NiceSlice
110              $y(0:4)           -->  Selects the first 5 elements from $y.
111

BASIC FEATURES

113       This section explains how PDL's syntax differs from Scilab. Most Scilab
114       users will want to start here.
115
116   General "gotchas"
117       Indices
118            In PDL, indices start at '0' (like C and Java), not 1 (like
119            Scilab).  For example, if $y is an array with 5 elements, the
120            elements would be numbered from 0 to 4.
121
122       Displaying an object
123            Scilab normally displays object contents automatically. In PDL you
124            display objects explicitly with the "print" command or the
125            shortcut "p":
126
127            Scilab:
128
129             --> a = 12
130             a =  12.
131             --> b = 23;       // Suppress output.
132             -->
133
134            PerlDL:
135
136             pdl> $x = 12    # No output.
137             pdl> print $x   # Print object.
138             12
139             pdl> p $x       # "p" is a shorthand for "print" in the shell.
140             12
141
142   Creating ndarrays
143       Variables in PDL
144            Variables always start with the '$' sign.
145
146             Scilab:    value  = 42
147             PerlDL:    $value = 42
148
149       Basic syntax
150            Use the "pdl" constructor to create a new ndarray.
151
152             Scilab:    v  = [1,2,3,4]
153             PerlDL:    $v = pdl [1,2,3,4]
154
155             Scilab:    A  =      [ 1,2,3  ;  3,4,5 ]
156             PerlDL:    $A = pdl [ [1,2,3] , [3,4,5] ]
157
158       Simple matrices
159                                  Scilab       PDL
160                                  ------       ------
161              Matrix of ones      ones(5,5)    ones 5,5
162              Matrix of zeros     zeros(5,5)   zeros 5,5
163              Random matrix       rand(5,5)    random 5,5
164              Linear vector       1:5          sequence 5
165
166            Notice that in PDL the parenthesis in a function call are often
167            optional.  It is important to keep an eye out for possible
168            ambiguities. For example:
169
170              pdl> p zeros 2, 2 + 2
171
172            Should this be interpreted as "zeros(2,2) + 2" or as "zeros 2,
173            (2+2)"?  Both are valid statements:
174
175              pdl> p zeros(2,2) + 2
176              [
177               [2 2]
178               [2 2]
179              ]
180              pdl> p zeros 2, (2+2)
181              [
182               [0 0]
183               [0 0]
184               [0 0]
185               [0 0]
186              ]
187
188            Rather than trying to memorize Perl's order of precedence, it is
189            best to use parentheses to make your code unambiguous.
190
191       Linearly spaced sequences
192              Scilab:   --> linspace(2,10,5)
193                        ans = 2.  4.  6.  8.  10.
194
195              PerlDL:   pdl> p zeroes(5)->xlinvals(2,10)
196                        [2 4 6 8 10]
197
198            Explanation: Start with a 1-dimensional ndarray of 5 elements and
199            give it equally spaced values from 2 to 10.
200
201            Scilab has a single function call for this. On the other hand,
202            PDL's method is more flexible:
203
204              pdl> p zeros(5,5)->xlinvals(2,10)
205              [
206               [ 2  4  6  8 10]
207               [ 2  4  6  8 10]
208               [ 2  4  6  8 10]
209               [ 2  4  6  8 10]
210               [ 2  4  6  8 10]
211              ]
212              pdl> p zeros(5,5)->ylinvals(2,10)
213              [
214               [ 2  2  2  2  2]
215               [ 4  4  4  4  4]
216               [ 6  6  6  6  6]
217               [ 8  8  8  8  8]
218               [10 10 10 10 10]
219              ]
220              pdl> p zeros(3,3,3)->zlinvals(2,6)
221              [
222               [
223                [2 2 2]
224                [2 2 2]
225                [2 2 2]
226               ]
227               [
228                [4 4 4]
229                [4 4 4]
230                [4 4 4]
231               ]
232               [
233                [6 6 6]
234                [6 6 6]
235                [6 6 6]
236               ]
237              ]
238
239       Slicing and indices
240            Extracting a subset from a collection of data is known as slicing.
241            The PDL shell and Scilab have a similar syntax for slicing, but
242            there are two important differences:
243
244            1) PDL indices start at 0, as in C and Java. Scilab starts indices
245            at 1.
246
247            2) In Scilab you think "rows and columns". In PDL, think "x and
248            y".
249
250              Scilab                         PerlDL
251              ------                         ------
252              --> A                           pdl> p $A
253              A =                            [
254                   1.  2.  3.                 [1 2 3]
255                   4.  5.  6.                 [4 5 6]
256                   7.  8.  9.                 [7 8 9]
257                                             ]
258              -------------------------------------------------------
259              (row = 2, col = 1)             (x = 0, y = 1)
260              --> A(2,1)                      pdl> p $A(0,1)
261              ans =                          [
262                     4.                       [4]
263                                             ]
264              -------------------------------------------------------
265              (row = 2 to 3, col = 1 to 2)   (x = 0 to 1, y = 1 to 2)
266              --> A(2:3,1:2)                  pdl> p $A(0:1,1:2)
267              ans =                          [
268                     4.  5.                   [4 5]
269                     7.  8.                   [7 8]
270                                             ]
271
272            Warning
273                 When you write a stand-alone PDL program you have to include
274                 the PDL::NiceSlice module. See the previous section "MODULES
275                 FOR SCILAB USERS" for more information.
276
277                   use PDL;             # Import main PDL module.
278                   use PDL::NiceSlice;  # Nice syntax for slicing.
279
280                   $A = random 4,4;
281                   print $A(0,1);
282
283   Matrix Operations
284       Matrix multiplication
285                  Scilab:    A * B
286                  PerlDL:    $A x $B
287
288       Element-wise multiplication
289                  Scilab:    A .* B
290                  PerlDL:    $A * $B
291
292       Transpose
293                  Scilab:    A'
294                  PerlDL:    $A->transpose
295
296   Functions that aggregate data
297       Some functions (like "sum", "max" and "min") aggregate data for an
298       N-dimensional data set. Scilab and PDL both give you the option to
299       apply these functions to the entire data set or to just one dimension.
300
301       Scilab    In Scilab, these functions work along the entire data set by
302                 default, and an optional parameter "r" or "c" makes them act
303                 over rows or columns.
304
305                   --> A = [ 1,5,4  ;  4,2,1 ]
306                   A = 1.  5.  4.
307                       4.  2.  1.
308                   --> max(A)
309                   ans = 5
310                   --> max(A, "r")
311                   ans = 4.    5.    4.
312                   --> max(A, "c")
313                   ans = 5.
314                         4.
315
316       PDL       PDL offers two functions for each feature.
317
318                   sum   vs   sumover
319                   avg   vs   average
320                   max   vs   maximum
321                   min   vs   minimum
322
323                 The long name works over a dimension, while the short name
324                 works over the entire ndarray.
325
326                   pdl> p $A = pdl [ [1,5,4] , [4,2,1] ]
327                   [
328                    [1 5 4]
329                    [4 2 1]
330                   ]
331                   pdl> p $A->maximum
332                   [5 4]
333                   pdl> p $A->transpose->maximum
334                   [4 5 4]
335                   pdl> p $A->max
336                   5
337
338   Higher dimensional data sets
339       A related issue is how Scilab and PDL understand data sets of higher
340       dimension. Scilab was designed for 1D vectors and 2D matrices with
341       higher dimensional objects added on top. In contrast, PDL was designed
342       for N-dimensional ndarrays from the start. This leads to a few
343       surprises in Scilab that don't occur in PDL:
344
345       Scilab sees a vector as a 2D matrix.
346              Scilab                       PerlDL
347              ------                       ------
348              --> vector = [1,2,3,4];       pdl> $vector = pdl [1,2,3,4]
349              --> size(vector)              pdl> p $vector->dims
350              ans = 1 4                    4
351
352            Scilab sees "[1,2,3,4]" as a 2D matrix (1x4 matrix). PDL sees it
353            as a 1D vector: A single dimension of size 4.
354
355       But Scilab ignores the last dimension of a 4x1x1 matrix.
356              Scilab                       PerlDL
357              ------                       ------
358              --> A = ones(4,1,1);          pdl> $A = ones 4,1,1
359              --> size(A)                   pdl> p $A->dims
360              ans = 4 1                    4 1 1
361
362       And Scilab treats a 4x1x1 matrix differently from a 1x1x4 matrix.
363              Scilab                       PerlDL
364              ------                       ------
365              --> A = ones(1,1,4);          pdl> $A = ones 1,1,4
366              --> size(A)                   pdl> p $A->dims
367              ans = 1 1 4                  1 1 4
368
369       Scilab has no direct syntax for N-D arrays.
370              pdl> $A = pdl [ [[1,2,3],[4,5,6]], [[2,3,4],[5,6,7]] ]
371              pdl> p $A->dims
372              3 2 2
373
374       Feature support.
375            In Scilab, several features are not available for N-D arrays. In
376            PDL, just about any feature supported by 1D and 2D ndarrays, is
377            equally supported by N-dimensional ndarrays. There is usually no
378            distinction:
379
380              Scilab                       PerlDL
381              ------                       ------
382              --> A = ones(3,3,3);         pdl> $A = ones(3,3,3);
383              --> A'                       pdl> transpose $A
384                  => ERROR                         => OK
385
386   Loop Structures
387       Perl has many loop structures, but we will only show the one that is
388       most familiar to Scilab users:
389
390         Scilab              PerlDL
391         ------              ------
392         for i = 1:10        for $i (1..10) {
393             disp(i)             print $i
394         end                 }
395
396       Note Never use for-loops for numerical work. Perl's for-loops are
397            faster than Scilab's, but they both pale against a "vectorized"
398            operation.  PDL has many tools that facilitate writing vectorized
399            programs.  These are beyond the scope of this guide. To learn
400            more, see: PDL::Indexing, PDL::Broadcasting, and PDL::PP.
401
402            Likewise, never use 1..10 for numerical work, even outside a for-
403            loop.  1..10 is a Perl array. Perl arrays are designed for
404            flexibility, not speed. Use ndarrays instead. To learn more, see
405            the next section.
406
407   ndarrays vs Perl Arrays
408       It is important to note the difference between an ndarray and a Perl
409       array. Perl has a general-purpose array object that can hold any type
410       of element:
411
412         @perl_array = 1..10;
413         @perl_array = ( 12, "Hello" );
414         @perl_array = ( 1, 2, 3, \@another_perl_array, sequence(5) );
415
416       Perl arrays allow you to create powerful data structures (see Data
417       structures below), but they are not designed for numerical work.  For
418       that, use ndarrays:
419
420         $pdl = pdl [ 1, 2, 3, 4 ];
421         $pdl = sequence 10_000_000;
422         $pdl = ones 600, 600;
423
424       For example:
425
426         $points =  pdl  1..10_000_000    # 4.7 seconds
427         $points = sequence 10_000_000    # milliseconds
428
429       TIP: You can use underscores in numbers ("10_000_000" reads better than
430       10000000).
431
432   Conditionals
433       Perl has many conditionals, but we will only show the one that is most
434       familiar to Scilab users:
435
436         Scilab                          PerlDL
437         ------                          ------
438         if value > MAX                  if ($value > $MAX) {
439             disp("Too large")               print "Too large\n";
440         elseif value < MIN              } elsif ($value < $MIN) {
441             disp("Too small")               print "Too small\n";
442         else                            } else {
443             disp("Perfect!")                print "Perfect!\n";
444         end                             }
445
446       Note Here is a "gotcha":
447
448              Scilab:  elseif
449              PerlDL:  elsif
450
451            If your conditional gives a syntax error, check that you wrote
452            your "elsif"'s correctly.
453
454   TIMTOWDI (There Is More Than One Way To Do It)
455       One of the most interesting differences between PDL and other tools is
456       the expressiveness of the Perl language. TIMTOWDI, or "There Is More
457       Than One Way To Do It", is Perl's motto.
458
459       Perl was written by a linguist, and one of its defining properties is
460       that statements can be formulated in different ways to give the
461       language a more natural feel. For example, you are unlikely to say to a
462       friend:
463
464        "While I am not finished, I will keep working."
465
466       Human language is more flexible than that. Instead, you are more likely
467       to say:
468
469        "I will keep working until I am finished."
470
471       Owing to its linguistic roots, Perl is the only programming language
472       with this sort of flexibility. For example, Perl has traditional while-
473       loops and if-statements:
474
475         while ( ! finished() ) {
476             keep_working();
477         }
478
479         if ( ! wife_angry() ) {
480             kiss_wife();
481         }
482
483       But it also offers the alternative until and unless statements:
484
485         until ( finished() ) {
486             keep_working();
487         }
488
489         unless ( wife_angry() ) {
490             kiss_wife();
491         }
492
493       And Perl allows you to write loops and conditionals in "postfix" form:
494
495         keep_working() until finished();
496
497         kiss_wife() unless wife_angry();
498
499       In this way, Perl often allows you to write more natural, easy to
500       understand code than is possible in more restrictive programming
501       languages.
502
503   Functions
504       PDL's syntax for declaring functions differs significantly from
505       Scilab's.
506
507         Scilab                          PerlDL
508         ------                          ------
509         function retval = foo(x,y)      sub foo {
510             retval = x.**2 + x.*y           my ($x, $y) = @_;
511         endfunction                         return $x**2 + $x*$y;
512                                         }
513
514       Don't be intimidated by all the new syntax. Here is a quick run through
515       a function declaration in PDL:
516
517       1) "sub" stands for "subroutine".
518
519       2) "my" declares variables to be local to the function.
520
521       3) "@_" is a special Perl array that holds all the function parameters.
522       This might seem like a strange way to do functions, but it allows you
523       to make functions that take a variable number of parameters. For
524       example, the following function takes any number of parameters and adds
525       them together:
526
527         sub mysum {
528             my ($i, $total) = (0, 0);
529             for $i (@_) {
530                 $total += $i;
531             }
532             return $total;
533         }
534
535       4) You can assign values to several variables at once using the syntax:
536
537         ($x, $y, $z) = (1, 2, 3);
538
539       So, in the previous examples:
540
541         # This declares two local variables and initializes them to 0.
542         my ($i, $total) = (0, 0);
543
544         # This takes the first two elements of @_ and puts them in $x and $y.
545         my ($x, $y) = @_;
546
547       5) The "return" statement gives the return value of the function, if
548       any.
549

ADDITIONAL FEATURES

551   Data structures
552       To create complex data structures, Scilab uses "lists" and "structs".
553       Perl's arrays and hashes offer similar functionality. This section is
554       only a quick overview of what Perl has to offer. To learn more about
555       this, please go to <http://perldoc.perl.org/perldata.html> or run the
556       command "perldoc perldata".
557
558       Arrays
559            Perl arrays are similar to Scilab's lists. They are both a
560            sequential data structure that can contain any data type.
561
562              Scilab
563              ------
564              list( 1, 12, "hello", zeros(3,3) , list( 1, 2) );
565
566              PerlDL
567              ------
568              @array = ( 1, 12, "hello" , zeros(3,3), [ 1, 2 ] )
569
570            Notice that Perl array's start with the "@" prefix instead of the
571            "$" used by ndarrays.
572
573            To learn about Perl arrays, please go to
574            <http://perldoc.perl.org/perldata.html> or run the command
575            "perldoc perldata".
576
577       Hashes
578            Perl hashes are similar to Scilab's structure arrays:
579
580              Scilab
581              ------
582              --> drink = struct('type', 'coke', 'size', 'large', 'myarray', ones(3,3,3))
583              --> drink.type = 'sprite'
584              --> drink.price = 12          // Add new field to structure array.
585
586              PerlDL
587              ------
588              pdl> %drink = ( type => 'coke' , size => 'large', myndarray => ones(3,3,3) )
589              pdl> $drink{type} = 'sprite'
590              pdl> $drink{price} = 12   # Add new field to hash.
591
592            Notice that Perl hashes start with the "%" prefix instead of the
593            "@" for arrays and "$" used by ndarrays.
594
595            To learn about Perl hashes, please go to
596            <http://perldoc.perl.org/perldata.html> or run the command
597            "perldoc perldata".
598
599   Performance
600       PDL has powerful performance features, some of which are not normally
601       available in numerical computation tools. The following pages will
602       guide you through these features:
603
604       PDL::Indexing
605            Level: Beginner
606
607            This beginner tutorial covers the standard "vectorization" feature
608            that you already know from Scilab. Use this page to learn how to
609            avoid for-loops to make your program more efficient.
610
611       PDL::Broadcasting
612            Level: Intermediate
613
614            PDL's "vectorization" feature goes beyond what most numerical
615            software can do. In this tutorial you'll learn how to "broadcast"
616            over higher dimensions, allowing you to vectorize your program
617            further than is possible in Scilab.
618
619       Benchmarks
620            Level: Intermediate
621
622            Perl comes with an easy to use benchmarks module to help you find
623            how long it takes to execute different parts of your code. It is a
624            great tool to help you focus your optimization efforts. You can
625            read about it online (<http://perldoc.perl.org/Benchmark.html>) or
626            through the command "perldoc Benchmark".
627
628       PDL::PP
629            Level: Advanced
630
631            PDL's Pre-Processor is one of PDL's most powerful features. You
632            write a function definition in special markup and the pre-
633            processor generates real C code which can be compiled. With PDL:PP
634            you get the full speed of native C code without having to deal
635            with the full complexity of the C language.
636
637   Plotting
638       PDL has full-featured plotting abilities. Unlike Scilab, PDL relies
639       more on third-party libraries (pgplot and PLplot) for its 2D plotting
640       features.  Its 3D plotting and graphics uses OpenGL for performance and
641       portability.  PDL has three main plotting modules:
642
643       PDL::Graphics::PGPLOT
644            Best for: Plotting 2D functions and data sets.
645
646            This is an interface to the venerable PGPLOT library. PGPLOT has
647            been widely used in the academic and scientific communities for
648            many years. In part because of its age, PGPLOT has some
649            limitations compared to newer packages such as PLplot (e.g. no RGB
650            graphics).  But it has many features that still make it popular in
651            the scientific community.
652
653       PDL::Graphics::PLplot
654            Best for: Plotting 2D functions as well as 2D and 3D data sets.
655
656            This is an interface to the PLplot plotting library. PLplot is a
657            modern, open source library for making scientific plots.  It
658            supports plots of both 2D and 3D data sets. PLplot is best
659            supported for unix/linux/macosx platforms. It has an active
660            developers community and support for win32 platforms is improving.
661
662       PDL::Graphics::TriD
663            Best for: Plotting 3D functions.
664
665            The native PDL 3D graphics library using OpenGL as a backend for
666            3D plots and data visualization. With OpenGL, it is easy to
667            manipulate the resulting 3D objects with the mouse in real time.
668
669   Writing GUIs
670       Through Perl, PDL has access to all the major toolkits for creating a
671       cross platform graphical user interface. One popular option is wxPerl
672       (<http://wxperl.sourceforge.net>). These are the Perl bindings for
673       wxWidgets, a powerful GUI toolkit for writing cross-platform
674       applications.
675
676       wxWidgets is designed to make your application look and feel like a
677       native application in every platform. For example, the Perl IDE Padre
678       is written with wxPerl.
679
680   Xcos / Scicos
681       Xcos (formerly Scicos) is a graphical dynamical system modeler and
682       simulator. It is part of the standard Scilab distribution. PDL and Perl
683       do not have a direct equivalent to Scilab's Xcos. If this feature is
684       important to you, you should probably keep a copy of Scilab around for
685       that.
686
688       Copyright 2010 Daniel Carrera (dcarrera@gmail.com). You can distribute
689       and/or modify this document under the same terms as the current Perl
690       license.
691
692       See: http://dev.perl.org/licenses/
693
694
695
696perl v5.38.0                      2023-07-21                         SCILAB(1)
Impressum