1MATLAB(1) User Contributed Perl Documentation MATLAB(1)
2
6 PDL::MATLAB - A guide for MATLAB users.
7
9 If you are a MATLAB user, this page is for you. It explains the key
10 differences between MATLAB and PDL to help you get going as quickly as
11 possible.
12 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 MATLAB and PDL.
16
18 The key difference between MATLAB and PDL is Perl.
19 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 MATLAB
24 and PDL are a result of its Perl foundation.
25 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 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
35 MATLAB 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 "piddle" to give
39 a name to their data type.
40 A piddle consists of a series of numbers organized as an N-dimensional
42 data set. Piddles provide efficient storage and fast computation of
43 large N-dimensional matrices. They are highly optimized for numerical
44 work.
45 For more information, see "Piddles vs Perl Arrays" later in this
47 document.
48
50 Unlike MATLAB, PDL does not come with a dedicated IDE. It does however
51 come with an interactive shell and you can use a Perl IDE to develop
52 PDL programs.
53 PDL interactive shell
55 To start the interactive shell, open a terminal and run "perldl" or
56 "pdl2". As in MATLAB, the interactive shell is the best way to learn
57 the language. To exit the shell, type "exit", just like MATLAB.
58 Writing PDL programs
60 One popular IDE for Perl is called Padre (<http://padre.perlide.org>).
61 It is cross platform and easy to use.
62 Whenever you write a stand-alone PDL program (i.e. outside the "perldl"
64 or "pdl2" shell) you must start the program with "use PDL;". This
65 command imports the PDL module into Perl. Here is a sample PDL program:
66 use PDL; # Import main PDL module.
68 use PDL::NiceSlice; # Import additional PDL module.
69 use PDL::AutoLoader; # Import additional PDL module.
70 $b = pdl [2,3,4]; # Statements end in semicolon.
72 $A = pdl [ [1,2,3],[4,5,6] ]; # 2-dimensional matrix.
73 print $A x $b->transpose;
75 Save this file as "myprogram.pl" and run it with:
77 perl myprogram.pl
79 New: Flexible syntax
81 In current versions of PDL (version 2.4.7 or later) there is a flexible
82 matrix syntax that can look extremely similar to MATLAB:
83 1) Use a ';' to delimit rows:
85 $b = pdl q[ 2,3,4 ];
87 $A = pdl q[ 1,2,3 ; 4,5,6 ];
88 2) Use spaces to separate elements:
90 $b = pdl q[ 2 3 4 ];
92 $A = pdl q[ 1 2 3 ; 4 5 6 ];
93 Basically, as long as you put a "q" in front of the opening bracket,
95 PDL should "do what you mean". So you can write in a syntax that is
96 more comfortable for you.
97
99 There are two modules that MATLAB users will want to use:
100 PDL::NiceSlice
102 Gives PDL a syntax for slices (sub-matrices) that is shorter and
103 more familiar to MATLAB users.
104 % MATLAB
106 b(1:5) --> Selects the first 5 elements from b.
107 # PDL without NiceSlice
109 $b->slice("0:4") --> Selects the first 5 elements from $b.
110 # PDL with NiceSlice
112 $b(0:4) --> Selects the first 5 elements from $b.
113 PDL::AutoLoader
115 Provides a MATLAB-style autoloader for PDL. If an unknown function
116 "foo()" is called, PDL looks for a file called "foo.pdl". If it
117 finds one, it reads it.
118
120 This section explains how PDL's syntax differs from MATLAB. Most MATLAB
121 users will want to start here.
122 General "gotchas"
124 Indices
125 In PDL, indices start at '0' (like C and Java), not 1 (like MATLAB
126 or FORTRAN). For example, if $b is an array with 5 elements, the
127 elements would be numbered from 0 to 4.
128 Displaying an object
130 MATLAB normally displays object contents automatically. In the PDL
131 shells you display objects explicitly with the "print" command or
132 the shortcut "p":
133 MATLAB:
135 >> a = 12
137 a = 12
138 >> b = 23; % Suppress output.
139 >>
140 PDL Shell (perldl or pdl2):
142 pdl> $a = 12 # No output.
144 pdl> print $a # Print object.
145 12
146 pdl> p $a # "p" is a shorthand for "print" in the shell.
147 12
148 pdl>
149 Creating Piddles
151 Variables in PDL
152 Variables always start with the '$' sign.
153 MATLAB: value = 42
155 PerlDL: $value = 42
156 Basic syntax
158 Use the "pdl" constructor to create a new piddle.
159 MATLAB: v = [1,2,3,4]
161 PerlDL: $v = pdl [1,2,3,4]
162 MATLAB: A = [ 1,2,3 ; 3,4,5 ]
164 PerlDL: $A = pdl [ [1,2,3] , [3,4,5] ]
165 Simple matrices
167 MATLAB PDL
168 ------ ------
169 Matrix of ones ones(5) ones 5,5
170 Matrix of zeros zeros(5) zeros 5,5
171 Random matrix rand(5) random 5,5
172 Linear vector 1:5 sequence 5
173 Notice that in PDL the parenthesis in a function call are often
175 optional. It is important to keep an eye out for possible
176 ambiguities. For example:
177 pdl> p zeros 2, 2 + 2
179 Should this be interpreted as "zeros(2,2) + 2" or as "zeros 2,
181 (2+2)"? Both are valid statements:
182 pdl> p zeros(2,2) + 2
184 [
185 [2 2]
186 [2 2]
187 ]
188 pdl> p zeros 2, (2+2)
189 [
190 [0 0]
191 [0 0]
192 [0 0]
193 [0 0]
194 ]
195 Rather than trying to memorize Perl's order of precedence, it is
197 best to use parentheses to make your code unambiguous.
198 Linearly spaced sequences
200 MATLAB: >> linspace(2,10,5)
201 ans = 2 4 6 8 10
202 PerlDL: pdl> p zeroes(5)->xlinvals(2,10)
204 [2 4 6 8 10]
205 Explanation: Start with a 1-dimensional piddle of 5 elements and
207 give it equally spaced values from 2 to 10.
208 MATLAB has a single function call for this. On the other hand,
210 PDL's method is more flexible:
211 pdl> p zeros(5,5)->xlinvals(2,10)
213 [
214 [ 2 4 6 8 10]
215 [ 2 4 6 8 10]
216 [ 2 4 6 8 10]
217 [ 2 4 6 8 10]
218 [ 2 4 6 8 10]
219 ]
220 pdl> p zeros(5,5)->ylinvals(2,10)
221 [
222 [ 2 2 2 2 2]
223 [ 4 4 4 4 4]
224 [ 6 6 6 6 6]
225 [ 8 8 8 8 8]
226 [10 10 10 10 10]
227 ]
228 pdl> p zeros(3,3,3)->zlinvals(2,6)
229 [
230 [
231 [2 2 2]
232 [2 2 2]
233 [2 2 2]
234 ]
235 [
236 [4 4 4]
237 [4 4 4]
238 [4 4 4]
239 ]
240 [
241 [6 6 6]
242 [6 6 6]
243 [6 6 6]
244 ]
245 ]
246 Slicing and indices
248 Extracting a subset from a collection of data is known as slicing.
249 PDL and MATLAB have a similar syntax for slicing, but there are
250 two important differences:
251 1) PDL indices start at 0, as in C and Java. MATLAB starts indices
253 at 1.
254 2) In MATLAB you think "rows and columns". In PDL, think "x and
256 y".
257 MATLAB PerlDL
259 ------ ------
260 >> A pdl> p $A
261 A = [
262 1 2 3 [1 2 3]
263 4 5 6 [4 5 6]
264 7 8 9 [7 8 9]
265 ]
266 -------------------------------------------------------
267 (row = 2, col = 1) (x = 0, y = 1)
268 >> A(2,1) pdl> p $A(0,1)
269 ans = [
270 4 [4]
271 ]
272 -------------------------------------------------------
273 (row = 2 to 3, col = 1 to 2) (x = 0 to 1, y = 1 to 2)
274 >> A(2:3,1:2) pdl> p $A(0:1,1:2)
275 ans = [
276 4 5 [4 5]
277 7 8 [7 8]
278 ]
279 Warning
281 When you write a stand-alone PDL program you have to include
282 the PDL::NiceSlice module. See the previous section "MODULES
283 FOR MATLAB USERS" for more information.
284 use PDL; # Import main PDL module.
286 use PDL::NiceSlice; # Nice syntax for slicing.
287 use PDL::AutoLoader; # MATLAB-like autoloader.
288 $A = random 4,4;
290 print $A(0,1);
291 Matrix Operations
293 Matrix multiplication
294 MATLAB: A * B
295 PerlDL: $A x $B
296 Element-wise multiplication
298 MATLAB: A .* B
299 PerlDL: $A * $B
300 Transpose
302 MATLAB: A'
303 PerlDL: $A->transpose
304 Functions that aggregate data
306 Some functions (like "sum", "max" and "min") aggregate data for an
307 N-dimensional data set. This is a place where MATLAB and PDL take a
308 different approach:
309 In MATLAB, these functions all work along one dimension.
311 >> A = [ 1,5,4 ; 4,2,1 ]
312 A = 1 5 4
313 4 2 1
314 >> max(A)
315 ans = 4 5 4
316 >> max(A')
317 ans = 5 4
318 If you want the maximum for the entire data set, you can use
320 the special A(:) notation which basically turns the entire
321 data set into a single 1-dimensional vector.
322 >> max(A(:))
324 ans = 5
325 >> A = ones(2,2,2,2)
326 >> max(A(:))
327 ans = 1
328 PDL offers two functions for each feature.
330 sum vs sumover
331 avg vs average
332 max vs maximum
333 min vs minimum
334 The long name works over a dimension, while the short name
336 works over the entire piddle.
337 pdl> p $A = pdl [ [1,5,4] , [4,2,1] ]
339 [
340 [1 5 4]
341 [4 2 1]
342 ]
343 pdl> p $A->maximum
344 [5 4]
345 pdl> p $A->transpose->maximum
346 [4 5 4]
347 pdl> p $A->max
348 5
349 pdl> p ones(2,2,2)->max
350 1
351 pdl> p ones(2,2,2,2)->max
352 1
353 Note Notice that PDL aggregates horizontally while MATLAB aggregates
355 vertically. In other words:
356 MATLAB PerlDL
358 max(A) == $A->transpose->maximum
359 max(A') == $A->maximum
360 TIP: In MATLAB you think "rows and columns". In PDL, think "x and
362 y".
363 Higher dimensional data sets
365 A related issue is how MATLAB and PDL understand data sets of higher
366 dimension. MATLAB was designed for 1D vectors and 2D matrices. Higher
367 dimensional objects ("N-D arrays") were added on top. In contrast, PDL
368 was designed for N-dimensional piddles from the start. This leads to a
369 few surprises in MATLAB that don't occur in PDL:
370 MATLAB sees a vector as a 2D matrix.
372 MATLAB PerlDL
373 ------ ------
374 >> vector = [1,2,3,4]; pdl> $vector = pdl [1,2,3,4]
375 >> size(vector) pdl> p $vector->dims
376 ans = 1 4 4
377 MATLAB sees "[1,2,3,4]" as a 2D matrix (1x4 matrix). PDL sees it
379 as a 1D vector: A single dimension of size 4.
380 But MATLAB ignores the last dimension of a 4x1x1 matrix.
382 MATLAB PerlDL
383 ------ ------
384 >> A = ones(4,1,1); pdl> $A = ones 4,1,1
385 >> size(A) pdl> p $A->dims
386 ans = 4 1 4 1 1
387 And MATLAB treats a 4x1x1 matrix differently from a 1x1x4 matrix.
389 MATLAB PerlDL
390 ------ ------
391 >> A = ones(1,1,4); pdl> $A = ones 1,1,4
392 >> size(A) pdl> p $A->dims
393 ans = 1 1 4 1 1 4
394 MATLAB has no direct syntax for N-D arrays.
396 pdl> $A = pdl [ [[1,2,3],[4,5,6]], [[2,3,4],[5,6,7]] ]
397 pdl> p $A->dims
398 3 2 2
399 Feature support.
401 In MATLAB, several features such as sparse matrix support are not
402 available for N-D arrays. In PDL, just about any feature supported
403 by 1D and 2D piddles, is equally supported by N-dimensional
404 piddles. There is usually no distinction.
405 Loop Structures
407 Perl has many loop structures, but we will only show the one that is
408 most familiar to MATLAB users:
409 MATLAB PerlDL
411 ------ ------
412 for i = 1:10 for $i (1..10) {
413 disp(i) print $i
414 endfor }
415 Note Never use for-loops for numerical work. Perl's for-loops are
417 faster than MATLAB's, but they both pale against a "vectorized"
418 operation. PDL has many tools that facilitate writing vectorized
419 programs. These are beyond the scope of this guide. To learn
420 more, see: PDL::Indexing, PDL::Threading, and PDL::PP.
421 Likewise, never use 1..10 for numerical work, even outside a for-
423 loop. 1..10 is a Perl array. Perl arrays are designed for
424 flexibility, not speed. Use piddles instead. To learn more, see
425 the next section.
426 Piddles vs Perl Arrays
428 It is important to note the difference between a Piddle and a Perl
429 array. Perl has a general-purpose array object that can hold any type
430 of element:
431 @perl_array = 1..10;
433 @perl_array = ( 12, "Hello" );
434 @perl_array = ( 1, 2, 3, \@another_perl_array, sequence(5) );
435 Perl arrays allow you to create powerful data structures (see Data
437 structures below), but they are not designed for numerical work. For
438 that, use piddles:
439 $pdl = pdl [ 1, 2, 3, 4 ];
441 $pdl = sequence 10_000_000;
442 $pdl = ones 600, 600;
443 For example:
445 $points = pdl 1..10_000_000 # 4.7 seconds
447 $points = sequence 10_000_000 # milliseconds
448 TIP: You can use underscores in numbers ("10_000_000" reads better than
450 10000000).
451 Conditionals
453 Perl has many conditionals, but we will only show the one that is most
454 familiar to MATLAB users:
455 MATLAB PerlDL
457 ------ ------
458 if value > MAX if ($value > $MAX) {
459 disp("Too large") print "Too large\n";
460 elseif value < MIN } elsif ($value < $MIN) {
461 disp("Too small") print "Too small\n";
462 else } else {
463 disp("Perfect!") print "Perfect!\n";
464 end }
465 Note Here is a "gotcha":
467 MATLAB: elseif
469 PerlDL: elsif
470 If your conditional gives a syntax error, check that you wrote
472 your "elsif"'s correctly.
473 TIMTOWDI (There Is More Than One Way To Do It)
475 One of the most interesting differences between PDL and other tools is
476 the expressiveness of the Perl language. TIMTOWDI, or "There Is More
477 Than One Way To Do It", is Perl's motto.
478 Perl was written by a linguist, and one of its defining properties is
480 that statements can be formulated in different ways to give the
481 language a more natural feel. For example, you are unlikely to say to a
482 friend:
483 "While I am not finished, I will keep working."
485 Human language is more flexible than that. Instead, you are more likely
487 to say:
488 "I will keep working until I am finished."
490 Owing to its linguistic roots, Perl is the only programming language
492 with this sort of flexibility. For example, Perl has traditional while-
493 loops and if-statements:
494 while ( ! finished() ) {
496 keep_working();
497 }
498 if ( ! wife_angry() ) {
500 kiss_wife();
501 }
502 But it also offers the alternative until and unless statements:
504 until ( finished() ) {
506 keep_working();
507 }
508 unless ( wife_angry() ) {
510 kiss_wife();
511 }
512 And Perl allows you to write loops and conditionals in "postfix" form:
514 keep_working() until finished();
516 kiss_wife() unless wife_angry();
518 In this way, Perl often allows you to write more natural, easy to
520 understand code than is possible in more restrictive programming
521 languages.
522 Functions
524 PDL's syntax for declaring functions differs significantly from
525 MATLAB's.
526 MATLAB PerlDL
528 ------ ------
529 function retval = foo(x,y) sub foo {
530 retval = x.**2 + x.*y my ($x, $y) = @_;
531 endfunction return $x**2 + $x*$y;
532 }
533 Don't be intimidated by all the new syntax. Here is a quick run through
535 a function declaration in PDL:
536 1) "sub" stands for "subroutine".
538 2) "my" declares variables to be local to the function.
540 3) "@_" is a special Perl array that holds all the function parameters.
542 This might seem like a strange way to do functions, but it allows you
543 to make functions that take a variable number of parameters. For
544 example, the following function takes any number of parameters and adds
545 them together:
546 sub mysum {
548 my ($i, $total) = (0, 0);
549 for $i (@_) {
550 $total += $i;
551 }
552 return $total;
553 }
554 4) You can assign values to several variables at once using the syntax:
556 ($a, $b, $c) = (1, 2, 3);
558 So, in the previous examples:
560 # This declares two local variables and initializes them to 0.
562 my ($i, $total) = (0, 0);
563 # This takes the first two elements of @_ and puts them in $x and $y.
565 my ($x, $y) = @_;
566 5) The "return" statement gives the return value of the function, if
568 any.
569
571 ASCII File IO
572 To read data files containing whitespace separated columns of numbers
573 (as would be read using the MATLAB load command) one uses the PDL rcols
574 in PDL::IO::Misc. For a general review of the IO functionality
575 available in PDL, see the documentation for PDL::IO, e.g., "help
576 PDL::IO" in the pdl2 shell or " pdldoc PDL::IO " from the shell command
577 line.
578 Data structures
580 To create complex data structures, MATLAB uses "cell arrays" and
581 "structure arrays". Perl's arrays and hashes offer similar
582 functionality but are more powerful and flexible. This section is only
583 a quick overview of what Perl has to offer. To learn more about this,
584 please go to <http://perldoc.perl.org/perldata.html> or run the command
585 "perldoc perldata".
586 Arrays
588 Perl arrays are similar to MATLAB's cell arrays, but more
589 flexible. For example, in MATLAB, a cell array is still
590 fundamentally a matrix. It is made of rows, and rows must have the
591 same length.
592 MATLAB
594 ------
595 array = {1, 12, 'hello'; rand(3, 2), ones(3), 'junk'}
596 => OK
597 array = {1, 12, 'hello'; rand(3, 2), ones(3) }
598 => ERROR
599 A Perl array is a general purpose, sequential data structure. It
601 can contain any data type.
602 PerlDL
604 ------
605 @array = ( [1, 12, 'hello'] , [ random(3,2), ones(3,3), 'junk' ] )
606 => OK
607 @array = ( [1, 12, 'hello'] , [ random(3,2), ones(3,3) ] )
608 => OK
609 @array = ( 5 , {'name' => 'Mike'} , [1, 12, 'hello'] )
610 => OK
611 Notice that Perl array's start with the "@" prefix instead of the
613 "$" used by piddles.
614 To learn about Perl arrays, please go to
616 <http://perldoc.perl.org/perldata.html> or run the command
617 "perldoc perldata".
618 Hashes
620 Perl hashes are similar to MATLAB's structure arrays:
621 MATLAB
623 ------
624 >> drink = struct('type', 'coke', 'size', 'large', 'myarray', {1,2,3})
625 >> drink.type = 'sprite'
626 >> drink.price = 12 % Add new field to structure array.
627 PerlDL
629 ------
630 pdl> %drink = ( type => 'coke' , size => 'large', mypiddle => ones(3,3,3) )
631 pdl> $drink{type} = 'sprite'
632 pdl> $drink{price} = 12 # Add new field to hash.
633 Notice that Perl hashes start with the "%" prefix instead of the
635 "@" for arrays and "$" used by piddles.
636 To learn about Perl hashes, please go to
638 <http://perldoc.perl.org/perldata.html> or run the command
639 "perldoc perldata".
640 Performance
642 PDL has powerful performance features, some of which are not normally
643 available in numerical computation tools. The following pages will
644 guide you through these features:
645 PDL::Indexing
647 Level: Beginner
648 This beginner tutorial covers the standard "vectorization" feature
650 that you already know from MATLAB. Use this page to learn how to
651 avoid for-loops to make your program more efficient.
652 PDL::Threading
654 Level: Intermediate
655 PDL's "vectorization" feature goes beyond what most numerical
657 software can do. In this tutorial you'll learn how to "thread"
658 over higher dimensions, allowing you to vectorize your program
659 further than is possible in MATLAB.
660 Benchmarks
662 Level: Intermediate
663 Perl comes with an easy to use benchmarks module to help you find
665 how long it takes to execute different parts of your code. It is a
666 great tool to help you focus your optimization efforts. You can
667 read about it online (<http://perldoc.perl.org/Benchmark.html>) or
668 through the command "perldoc Benchmark".
669 PDL::PP
671 Level: Advanced
672 PDL's Pre-Processor is one of PDL's most powerful features. You
674 write a function definition in special markup and the pre-
675 processor generates real C code which can be compiled. With PDL:PP
676 you get the full speed of native C code without having to deal
677 with the full complexity of the C language.
678 Plotting
680 PDL has full-featured plotting abilities. Unlike MATLAB, PDL relies
681 more on third-party libraries (pgplot and PLplot) for its 2D plotting
682 features. Its 3D plotting and graphics uses OpenGL for performance and
683 portability. PDL has three main plotting modules:
684 PDL::Graphics::PGPLOT
686 Best for: Plotting 2D functions and data sets.
687 This is an interface to the venerable PGPLOT library. PGPLOT has
689 been widely used in the academic and scientific communities for
690 many years. In part because of its age, PGPLOT has some
691 limitations compared to newer packages such as PLplot (e.g. no RGB
692 graphics). But it has many features that still make it popular in
693 the scientific community.
694 PDL::Graphics::PLplot
696 Best for: Plotting 2D functions as well as 2D and 3D data sets.
697 This is an interface to the PLplot plotting library. PLplot is a
699 modern, open source library for making scientific plots. It
700 supports plots of both 2D and 3D data sets. PLplot is best
701 supported for unix/linux/macosx platforms. It has an active
702 developers community and support for win32 platforms is improving.
703 PDL::Graphics::TriD
705 Best for: Plotting 3D functions.
706 The native PDL 3D graphics library using OpenGL as a backend for
708 3D plots and data visualization. With OpenGL, it is easy to
709 manipulate the resulting 3D objects with the mouse in real time.
710 Writing GUIs
712 Through Perl, PDL has access to all the major toolkits for creating a
713 cross platform graphical user interface. One popular option is wxPerl
714 (<http://wxperl.sourceforge.net>). These are the Perl bindings for
715 wxWidgets, a powerful GUI toolkit for writing cross-platform
716 applications.
717 wxWidgets is designed to make your application look and feel like a
719 native application in every platform. For example, the Perl IDE Padre
720 is written with wxPerl.
721 Simulink
723 Simulink is a graphical dynamical system modeler and simulator. It can
724 be purchased separately as an add-on to MATLAB. PDL and Perl do not
725 have a direct equivalent to MATLAB's Simulink. If this feature is
726 important to you, then take a look at Scilab:
727 <http://www.scilab.org>
729 Scilab is another numerical analysis software. Like PDL, it is free and
731 open source. It doesn't have PDL's unique features, but it is very
732 similar to MATLAB. Scilab comes with Xcos (previously Scicos), a
733 graphical system modeler and simulator similar to Simulink.
734
736 Copyright 2010 Daniel Carrera (dcarrera@gmail.com). You can distribute
737 and/or modify this document under the same terms as the current Perl
738 license.
739 See: http://dev.perl.org/licenses/
741 Acknowledgements
743 I'd like to thank David Mertens, Chris Marshall and Sigrid Carrera
744 for their immense help reviewing earlier drafts of this guide.
745 Without their hours of work, this document would not be remotely
746 as useful to MATLAB users as it is today.
747perl v5.30.0 2019-09-05 MATLAB(1)