2866
|
1 \input texinfo.tex @c -*-texinfo-*- |
|
2 |
3030
|
3 @setfilename Octave-FAQ.info |
2866
|
4 @settitle Frequently asked questions about Octave (with answers) |
|
5 |
|
6 @setchapternewpage off |
5099
|
7 @direntry |
6584
|
8 * Octave-FAQ: (Octave-FAQ). Frequently asked questions about Octave |
5099
|
9 @end direntry |
2866
|
10 @titlepage |
|
11 @title Octave FAQ |
|
12 @subtitle Frequently asked questions about Octave |
6583
|
13 @subtitle April, 2007 |
2866
|
14 @sp 1 |
|
15 @author John W. Eaton |
|
16 @page |
|
17 @end titlepage |
|
18 |
5423
|
19 @ifnottex |
4830
|
20 @node Top |
2866
|
21 @top |
|
22 @unnumbered Preface |
|
23 @cindex FAQ for Octave, latest version |
5423
|
24 @end ifnottex |
2866
|
25 |
|
26 This is a list of frequently asked questions (FAQ) for Octave users. |
|
27 |
6584
|
28 We are always looking for new questions (@emph{with} answers), better |
|
29 answers, or both. Please send suggestions to @email{bug@@octave.org}. |
|
30 If you have general questions about Octave, or need help for something |
|
31 that is not covered by the Octave manual or the FAQ, please use the |
|
32 @email{help@@octave.org} mailing list. |
2866
|
33 |
|
34 This FAQ is intended to supplement, not replace, the Octave manual. |
6584
|
35 Before posting a question to the @email{help@@octave.org} mailing list, |
|
36 you should first check to see if the topic is covered in the manual. |
2866
|
37 |
|
38 @menu |
6583
|
39 * What is Octave?:: |
|
40 * How can I cite Octave?:: |
|
41 * Series 2.9.N:: |
|
42 * Octave Features:: |
|
43 * Learning more about Octave:: |
|
44 * Getting Octave:: |
|
45 * Installation:: |
2866
|
46 * Common problems:: |
6584
|
47 * How do I ...?:: |
6583
|
48 * MATLAB compatibility:: |
2866
|
49 * Index:: |
|
50 @end menu |
|
51 |
4830
|
52 @node What is Octave? |
2866
|
53 @chapter What is Octave? |
|
54 |
|
55 Octave is a high-level interactive language, primarily intended for |
|
56 numerical computations that is mostly compatible with |
|
57 @sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks, |
6583
|
58 Inc.} |
2866
|
59 |
6583
|
60 Octave can do arithmetic for real, complex or integer-valued scalars |
|
61 and matrices, solve sets of nonlinear algebraic equations, integrate |
|
62 functions over finite and infinite intervals, and integrate systems of |
|
63 ordinary differential and differential-algebraic equations. |
2866
|
64 |
|
65 Octave uses the GNU readline library to handle reading and editing |
|
66 input. By default, the line editing commands are similar to the |
|
67 cursor movement commands used by GNU Emacs, and a vi-style line |
|
68 editing interface is also available. At the end of each session, the |
|
69 command history is saved, so that commands entered during previous |
|
70 sessions are not lost. |
|
71 |
6606
|
72 The Octave distribution includes a 550+ page Texinfo manual. Access |
2866
|
73 to the complete text of the manual is available via the help command |
6583
|
74 @c really, the *complete* text? |
2866
|
75 at the Octave prompt. |
|
76 |
6583
|
77 @menu |
|
78 * Who develops Octave?:: |
6584
|
79 * Why GNU Octave?:: |
6583
|
80 * What version should I use?:: |
|
81 * On what platforms does Octave run?:: |
|
82 @end menu |
|
83 |
|
84 @node Who develops Octave? |
|
85 @section Who develops Octave? |
|
86 |
6584
|
87 Discussions about writing the software that would eventually become |
|
88 Octave started in about 1988 with James B. Rawlings and John W. Eaton at |
|
89 the University of Texas. John W. Eaton was the original author of |
|
90 Octave, starting full-time development in February 1992. He is still |
|
91 the primary maintainer. The community |
|
92 of users/developers has in addition contributed some code and fuels the |
|
93 discussion on the mailing lists @email{help@@octave.org} (user forum), |
|
94 @email{bug@@octave.org} (bug reports), @email{maintainers@@octave.org} |
|
95 (development issues), and @email{octave-dev@@lists.sourceforge.net} (all |
|
96 things related to the Octave Forge repository of user-contributed |
|
97 functions). |
6583
|
98 |
6584
|
99 @node Why GNU Octave? |
|
100 @section Why GNU Octave? |
6583
|
101 |
6584
|
102 The GNU Project was launched in 1984 to develop a complete Unix-like |
|
103 operating system which is free software: the GNU system. |
|
104 |
|
105 GNU is a recursive acronym for ``GNU's Not Unix''; it is pronounced |
|
106 guh-noo, approximately like canoe. |
6583
|
107 |
6584
|
108 The Free Software Foundation (FSF) is the principal organizational |
|
109 sponsor of the GNU Project. |
|
110 |
|
111 Octave became GNU Octave in 1997 (beginning with version 2.0.6). This |
|
112 meant agreeing to consider Octave a part of the GNU Project and support |
|
113 the efforts of the FSF. However, Octave is not and has never been |
|
114 developed by the FSF. |
|
115 |
|
116 For more information about the GNU project, see @url{www.gnu.org}. |
6583
|
117 |
|
118 @cindex FSF [Free Software Foundation] |
|
119 @cindex GNU [GNU's not unix] |
|
120 |
|
121 @node What version should I use? |
|
122 @section What version should I use? |
|
123 |
|
124 In general, you will find the latest version on |
6584
|
125 @url{http://www.octave.org/download.html}. It is |
6583
|
126 recommended to use the ``testing'' version of octave for general use, |
|
127 and the ``development'' version if you want the latest features. |
|
128 |
|
129 A list of user-visible changes since the last release is available in |
|
130 the file @file{NEWS}. The file @file{ChangeLog} in the source |
|
131 distribution contains a more detailed record of changes made since the |
|
132 last release. |
|
133 |
|
134 @node On what platforms does Octave run? |
|
135 @section On what platforms does Octave run? |
|
136 |
6584
|
137 Octave runs on various Unices---at least Linux and Solaris, Mac OS X, |
|
138 Windows and anything you can compile it on. Binary distributions exist |
6583
|
139 at least for Debian, Suse, Fedora and RedHat Linuxes (Intel and AMD |
|
140 CPUs, at least), for Mac Os X and Windows' 98, 2000 and XP. |
|
141 |
2866
|
142 Two and three dimensional plotting is fully supported using gnuplot. |
|
143 |
|
144 The underlying numerical solvers are currently standard Fortran ones |
|
145 like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library |
|
146 of C++ classes. If possible, the Fortran subroutines are compiled |
|
147 with the system's Fortran compiler, and called directly from the C++ |
|
148 functions. If that's not possible, you can still compile Octave if |
|
149 you have the free Fortran to C translator f2c. |
|
150 |
|
151 Octave is also free software; you can redistribute it and/or modify it |
|
152 under the terms of the GNU General Public License as published by the |
|
153 Free Software Foundation. |
|
154 |
4830
|
155 @node How can I cite Octave? |
|
156 @chapter How can I cite Octave? |
4831
|
157 |
|
158 Pointing to @url{http://www.octave.org} is good, because that gives |
|
159 people a direct way to find out more. If citation of a URL is not |
|
160 allowed by a publisher, or if you also want to point to a traditional |
|
161 reference, then you can cite the Octave manual: |
4830
|
162 |
|
163 @example |
|
164 @group |
6584
|
165 @@BOOK@{eaton:2002, |
|
166 author = "John W. Eaton", |
|
167 title = "GNU Octave Manual", |
|
168 publisher = "Network Theory Limited", |
|
169 year = "2002", |
|
170 isbn = "0-9541617-2-6" |
|
171 @} |
4830
|
172 @end group |
|
173 @end example |
|
174 |
6583
|
175 @node Series 2.9.N |
|
176 @chapter What's new in version series 2.9.N of Octave |
|
177 |
6584
|
178 The 2.9.N series, started in March 2005, has enough new features to |
|
179 justify a major version number change. Version 2.9.10 is nearly as |
6583
|
180 stable as the latest 2.1.N releases and stability should increase as |
|
181 one gets near version 3.0. |
|
182 |
|
183 Series 2.9.N brings |
|
184 |
|
185 @itemize @bullet |
|
186 |
|
187 @item integer types |
|
188 |
|
189 @item fixed point arithmetic |
|
190 |
|
191 @item sparse matrices |
|
192 |
|
193 @item Linear programming code based on GLPK |
|
194 |
|
195 @item 64-bit compilation support |
|
196 |
|
197 @item gzipped files and stream and consequently support of matlab v7 files |
2866
|
198 |
6583
|
199 @item better support for both msvc and mingw |
|
200 |
6606
|
201 @item a fully compatiable MEX interface |
6583
|
202 |
6606
|
203 @item many many other minor features and compatibility changes |
6583
|
204 |
|
205 @end itemize |
|
206 |
|
207 Here are some features that have been around since 2.1.NN |
|
208 |
|
209 @itemize @bullet |
2866
|
210 |
6583
|
211 @item NDarrays |
|
212 |
|
213 @item cells |
|
214 |
|
215 @end itemize |
|
216 |
4830
|
217 @node Octave Features |
2866
|
218 @chapter What features are unique to Octave? |
|
219 |
|
220 @menu |
6583
|
221 * Functions defined on the command-line:: |
|
222 * Comments with #:: |
|
223 * Strings delimitted by double quotes ":: |
|
224 * Line continuation by backslash:: |
|
225 * Informative block closing:: |
|
226 * Coherent syntax:: |
|
227 * Exclamation mark as not operator:: |
|
228 @c * Short-circuit boolean operators:: |
2866
|
229 * Increment and decrement operators:: |
|
230 * Unwind-protect:: |
6583
|
231 * Built-in ODE and DAE solvers:: |
2866
|
232 @end menu |
|
233 |
6583
|
234 This section refers to Matlab 6,5.0 R 13 and Octave 2.9.10. |
2866
|
235 |
6583
|
236 @node Functions defined on the command-line |
|
237 @section Functions defined on the command-line |
2866
|
238 |
6583
|
239 Functions can be defined by entering code on the command line, a |
6584
|
240 feature not supported by the other leading brand. For example, you may |
6583
|
241 type: |
2866
|
242 |
|
243 @example |
|
244 @group |
6583
|
245 octave:1> function s = hello_string (to_who) |
|
246 > ## Say hello |
|
247 > if nargin<1, to_who = "World"; end |
|
248 > s = ["Hello ",\ |
|
249 > to_who]; |
|
250 > endfunction |
|
251 octave:2> hello_string ("Moon") |
|
252 ans = Hello Moon |
2866
|
253 @end group |
|
254 @end example |
|
255 |
6583
|
256 @node Comments with # |
|
257 @section Comments with # |
|
258 |
6584
|
259 The pound character, @samp{#}, may be used to start comments, in addition |
|
260 to @samp{%}. See the previous example. The major advantage of this is |
|
261 that as @samp{#} is also a comment character for unix script files, any |
|
262 file that starts with a string like @samp{#! /usr/bin/octave -q} will be |
|
263 treated as an octave script and be executed by octave. |
2866
|
264 |
6583
|
265 @node Strings delimitted by double quotes " |
|
266 @section Strings delimitted by double quotes " |
6584
|
267 The double quote, @samp{"}, may be used to delimit strings, in addition to |
|
268 the single quote @samp{'}. See the previous example. Also, double-quoted |
|
269 strings include backslash interpretation (like C++, C, and Perl) while |
|
270 single quoted are uninterpreted (like Matlab and Perl). |
6583
|
271 |
|
272 @node Line continuation by backslash |
|
273 @section Line continuation by backslash |
|
274 |
6584
|
275 Lines can be continued with a backslash, @samp{\}, in addition to three |
|
276 points @samp{@dots{}}. See the previous example. |
6583
|
277 |
|
278 @node Informative block closing |
|
279 @section Informative block closing |
|
280 |
6584
|
281 You may close @code{function}, @code{for}, @code{while}, @code{if}, |
|
282 @dots{} blocks with @code{endfunction}, @code{endfor}, @code{endwhile}, |
|
283 @dots{} keywords in addition to using @code{end}. As with Matlab, the |
|
284 @code{end} (or @code{endfunction}) keyword that marks the end of a |
|
285 function defined in a @file{.m} file is optional. |
2866
|
286 |
6583
|
287 @node Coherent syntax |
|
288 @section Coherent syntax |
|
289 |
|
290 Indexing other things than variables is possible, as in: |
|
291 @example |
|
292 @group |
|
293 octave:1> [3 1 4 1 5 9](3) |
|
294 ans = 4 |
|
295 octave:2> cos([0 pi pi/4 7])(3) |
|
296 ans = 0.70711 |
|
297 @end group |
|
298 @end example |
|
299 |
|
300 @node Exclamation mark as not operator |
|
301 @section Exclamation mark as not operator |
|
302 |
|
303 The exclamation mark '!' (aka ``Bang!'') is a negation operator, just |
|
304 like the tilde '~': |
2866
|
305 |
|
306 @example |
|
307 @group |
6583
|
308 octave:1> if ! strcmp (program_name, "octave"), |
|
309 > "It's an error" |
|
310 > else |
|
311 > "It works!" |
|
312 > end |
|
313 ans = It works! |
2866
|
314 @end group |
|
315 @end example |
|
316 |
4830
|
317 @node Increment and decrement operators |
2866
|
318 @section Increment and decrement operators |
|
319 |
|
320 @cindex Increment operators |
|
321 @cindex Decrement operators |
|
322 @cindex Operators, increment |
|
323 @cindex Operators, decrement |
|
324 |
6584
|
325 If you like the @samp{++}, @samp{+=} etc operators, rejoice! |
2866
|
326 Octave includes the C-like increment and decrement operators @samp{++} |
6583
|
327 and @samp{--} in both their prefix and postfix forms, in addition to |
|
328 @samp{+=}, @samp{-=}, @samp{*=}, @samp{/=}, @samp{^=}, @samp{.*=}, |
|
329 @samp{./=}, and @samp{.^=}. |
2866
|
330 |
|
331 For example, to pre-increment the variable @var{x}, you would write |
|
332 @code{++@var{x}}. This would add one to @var{x} and then return the new |
|
333 value of @var{x} as the result of the expression. It is exactly the |
|
334 same as the expression @code{@var{x} = @var{x} + 1}. |
|
335 |
6584
|
336 To post-increment a variable @var{x}, you would write @code{x++}. |
2866
|
337 This adds one to the variable @var{x}, but returns the value that |
|
338 @var{x} had prior to incrementing it. For example, if @var{x} is equal |
6584
|
339 to 2, the result of the expression @code{x++} is 2, and the new |
2866
|
340 value of @var{x} is 3. |
|
341 |
|
342 For matrix and vector arguments, the increment and decrement operators |
|
343 work on each element of the operand. |
|
344 |
|
345 |
4830
|
346 @node Unwind-protect |
2866
|
347 @section Unwind-protect |
|
348 |
|
349 @cindex Unwind-protect |
|
350 |
|
351 Octave supports a limited form of exception handling modelled after the |
|
352 unwind-protect form of Lisp. The general form of an |
|
353 @code{unwind_protect} block looks like this: |
|
354 |
|
355 @example |
|
356 @group |
|
357 unwind_protect |
|
358 @var{body} |
|
359 unwind_protect_cleanup |
|
360 @var{cleanup} |
|
361 end_unwind_protect |
|
362 @end group |
|
363 @end example |
|
364 |
|
365 @noindent |
|
366 Where @var{body} and @var{cleanup} are both optional and may contain any |
|
367 Octave expressions or commands. The statements in @var{cleanup} are |
|
368 guaranteed to be executed regardless of how control exits @var{body}. |
|
369 |
|
370 The @code{unwind_protect} statement is often used to reliably restore |
|
371 the values of global variables that need to be temporarily changed. |
|
372 |
4830
|
373 @node Built-in ODE and DAE solvers |
2866
|
374 @section Built-in ODE and DAE solvers |
|
375 |
|
376 @cindex DASSL |
|
377 @cindex LSODE |
|
378 |
|
379 Octave includes LSODE and DASSL for solving systems of stiff ordinary |
|
380 differential and differential-algebraic equations. These functions are |
|
381 built in to the interpreter. |
|
382 |
6583
|
383 @node Learning more about Octave |
|
384 @chapter What documentation exists for Octave? |
|
385 |
|
386 @menu |
|
387 * Documentation:: |
|
388 * Getting additional help:: |
|
389 * User community:: |
|
390 * Bug reports:: |
|
391 @end menu |
|
392 |
|
393 |
4830
|
394 @node Documentation |
6583
|
395 @section What documentation exists for Octave? |
2866
|
396 |
|
397 @cindex Octave, documentation |
|
398 |
6584
|
399 The Octave distribution includes a 550+ page manual that is also |
2866
|
400 distributed under the terms of the GNU GPL. |
6583
|
401 It is available on the web at |
|
402 @url{http://www.octave.org/docs.html} and you will also |
|
403 find there instructions on how to order a paper version. |
|
404 |
|
405 The complete text of the Octave manual is also available using the GNU |
|
406 Info system via the GNU Emacs, info, or xinfo programs, or by using |
|
407 the @samp{help -i} command to start the GNU info browser directly from |
|
408 the Octave prompt. |
|
409 |
|
410 If you have problems using this documentation, or find that some topic |
|
411 is not adequately explained, indexed, or cross-referenced, please send |
6584
|
412 a bug report to @email{bug@@octave.org}. |
6583
|
413 |
2866
|
414 |
6583
|
415 @node Getting additional help |
|
416 @section Getting additional help |
|
417 |
|
418 @cindex Additional help |
|
419 @cindex Mailing lists, help-octave |
|
420 |
6584
|
421 If you can't find an answer to your question, the |
|
422 @email{help@@octave.org} mailing list is available for questions related |
|
423 to using, installing, and porting Octave that are not adequately |
|
424 answered by the Octave manual or by this document. |
6583
|
425 |
|
426 @node User community |
|
427 @section User community |
|
428 |
6584
|
429 To subscribe to the list, go to @url{www.octave.org/archive.html} and |
|
430 follow the link to the subscription page for the list. |
2866
|
431 |
6653
|
432 @strong{Please do not} send requests to be added or removed from the |
6583
|
433 mailing list, or other administrative trivia to the list itself. |
|
434 |
|
435 An archive of old postings to the help-octave mailing list is maintained |
|
436 on @url{http://www.octave.org/archive.html}. |
|
437 |
6584
|
438 You will also find some user advice and code spread over the web. Good |
6583
|
439 starting points are the Octave Wiki @url{http://wiki.octave.org} and |
|
440 Octave-Forge @url{htt://octave.sourceforge.net} |
|
441 |
|
442 @node Bug reports |
|
443 @section I think I have found a bug in Octave. |
|
444 |
|
445 @cindex Bug in Octave, newly found |
|
446 |
|
447 ``I think I have found a bug in Octave, but I'm not sure. How do I know, |
|
448 and who should I tell?'' |
2866
|
449 |
6583
|
450 @cindex Manual, for Octave |
|
451 |
|
452 First, see the section on bugs and bug reports in the Octave manual. |
|
453 When you report a bug, make sure to describe the type of computer you |
|
454 are using, the version of the operating system it is running, and the |
|
455 version of Octave that you are using. Also provide enough code so that |
|
456 the Octave maintainers can duplicate your bug. |
|
457 |
|
458 If you have Octave working at all, the easiest way to do this is to use |
|
459 the Octave function @code{bug_report}. When you execute this function, |
|
460 Octave will prompt you for a subject and then invoke the editor on a |
|
461 file that already contains all the configuration information. When you |
|
462 exit the editor, Octave will mail the bug report for you (in a unix-like |
|
463 operating system). |
|
464 |
|
465 @cindex Octave bug report |
|
466 @cindex Mailing lists, bug-octave |
|
467 |
|
468 If for some reason you cannot use Octave's @code{bug_report} function, |
6584
|
469 mail your bug report to @email{bug@@octave.org}. Your message needs to |
6583
|
470 include enough information to allow the maintainers of Octave to fix the |
|
471 bug. Please read the section on bugs and bug reports in the Octave |
|
472 manual for a list of things that should be included in every bug report. |
|
473 |
2866
|
474 |
4830
|
475 @node Getting Octave |
6583
|
476 @chapter Getting Octave |
2866
|
477 |
|
478 @menu |
6583
|
479 * Source code:: |
|
480 * Pre-compiled binary packages:: |
|
481 * Octave for other platforms:: |
2866
|
482 @end menu |
|
483 |
6583
|
484 @node Source code |
|
485 @section Source code |
|
486 @cindex Source code |
2866
|
487 |
6583
|
488 Source code is available on the Octave development site, where you are |
|
489 sure to get the latest version. |
2866
|
490 |
6583
|
491 @itemize @bullet |
|
492 @item @url{http://www.octave.org/download.html} |
|
493 @item @url{ftp://ftp.octave.org/pub/octave/} |
|
494 @end itemize |
2866
|
495 |
6583
|
496 Since Octave is distrubted under the terms of the GPL, you can get |
|
497 Octave from a friend who has a copy, by anonymous FTP, or by ordering |
|
498 a tape or CD-ROM from the Free Software Foundation (FSF). |
2866
|
499 |
6583
|
500 @node Pre-compiled binary packages |
|
501 @section Pre-compiled binary packages |
|
502 @cindex Pre-compiled binary packages |
|
503 @cindex Binaries |
2866
|
504 |
6584
|
505 The Octave project does not distribute binary packages, but other |
|
506 projects do. For an up-to-date listing of packagers, see: |
2866
|
507 |
6583
|
508 @itemize @bullet |
|
509 @item @url{http://www.octave.org/download.html} |
|
510 @item @url{http://wiki.octave.org/wiki.pl?CategoryInstall} |
|
511 @end itemize |
2866
|
512 |
6583
|
513 As of today, Octave binaries are available at least on Debian, RedHat, |
|
514 Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP. |
2866
|
515 |
4830
|
516 @node Octave for other platforms |
2866
|
517 @section How do I get a copy of Octave for (some other platform)? |
|
518 |
|
519 @cindex VMS support |
|
520 @cindex VAX |
|
521 @cindex MS-DOS support |
3154
|
522 @cindex Windows support |
2866
|
523 @cindex DJGPP |
|
524 @cindex EMX |
|
525 @cindex OS/2 support |
|
526 |
6584
|
527 Octave currently runs on Unix-like systems, Mac OS X, and Windows |
3840
|
528 (using the Cygwin tools from Red Hat). It should be possible |
3154
|
529 to make Octave work on other systems as well. If you are interested in |
|
530 porting Octave to other systems, please contact |
6584
|
531 @email{bug@@octave.org}. |
2866
|
532 |
6583
|
533 @c @menu |
|
534 @c * Octave for Unix:: |
|
535 @c * Octave for other platforms:: |
|
536 @c * latest versions:: |
|
537 @c @end menu |
2866
|
538 |
6583
|
539 @c @cindex Octave, ordering |
|
540 @c @cindex Octave, getting a copy |
2866
|
541 |
4830
|
542 @node Installation |
2866
|
543 @chapter Installation Issues and Problems |
|
544 |
|
545 @cindex Octave, building |
|
546 |
6584
|
547 Octave 2.9.10 requires approximately 800MB of disk storage to unpack |
|
548 and compile from source (considerably less if you don't compile with |
|
549 debugging symbols). Once installed, Octave requires approximately 200MB |
|
550 of disk space (again, considerably less if you don't compile with |
|
551 debugging symbols). |
2866
|
552 |
|
553 @menu |
|
554 * What else do I need?:: |
|
555 * Other C++ compilers?:: |
|
556 @end menu |
|
557 |
4830
|
558 @node What else do I need? |
2866
|
559 @section What else do I need? |
|
560 |
|
561 @cindex GNU gcc |
|
562 @cindex GNU g++ |
|
563 @cindex libg++ |
|
564 @cindex GNU Make |
|
565 @cindex Flex |
|
566 @cindex GNU Bison |
|
567 |
3154
|
568 To compile Octave, you will need a recent version of GNU Make. You |
6584
|
569 will also need GCC 3.3 or later, although GCC 4.1 or later is |
|
570 recommended. |
3154
|
571 |
6584
|
572 @strong{You must have GNU Make to compile octave}. Octave's Makefiles |
3154
|
573 use features of GNU Make that are not present in other versions of make. |
|
574 GNU Make is very portable and easy to install. |
2866
|
575 |
4830
|
576 @node Other C++ compilers? |
2866
|
577 @section Can I compile Octave with another C++ compiler? |
|
578 |
6584
|
579 Yes, but development is done primarily with GCC, so you may hit some |
|
580 incompatibilities. Octave is intended to be portable to any standard |
|
581 conforming compiler. If you have difficulties that you think are bugs, |
|
582 please report them to the @email{bug@@octave.org} mailing list, or ask |
|
583 for help on the @email{help@@octave.org} mailing list. |
2866
|
584 |
4830
|
585 @node Common problems |
2866
|
586 @chapter Common problems |
|
587 |
|
588 This list is probably far too short. Feel free to suggest additional |
|
589 questions (preferably with answers!) |
|
590 |
|
591 @itemize @bullet |
|
592 @item |
|
593 Octave takes a long time to find symbols. |
|
594 |
6606
|
595 Octave uses the @code{genpath} function to recursively add directories |
|
596 to the list of directories searched for function files. Check the list |
|
597 of directories with the @code{path} command. If the path list is very |
|
598 long check your use of the @code{genpath} function. |
2866
|
599 @end itemize |
|
600 |
6584
|
601 @node How do I ...? |
|
602 @chapter How do I ...? |
2866
|
603 |
6583
|
604 @menu |
|
605 * How do I set the number of displayed decimals?:: |
|
606 @end menu |
2866
|
607 |
6583
|
608 @cindex Tips and tricks |
6584
|
609 @cindex How do I @dots{} ? |
2866
|
610 |
6583
|
611 @node How do I set the number of displayed decimals? |
|
612 @section How do I set the number of displayed decimals? |
2866
|
613 |
|
614 |
|
615 @example |
|
616 @group |
6583
|
617 octave:1> format long |
|
618 octave:2> pi |
|
619 pi = 3.14159265358979 |
|
620 octave:3> format short |
|
621 octave:4> pi |
|
622 pi = 3.1416 |
2866
|
623 @end group |
|
624 @end example |
|
625 |
4830
|
626 @node MATLAB compatibility |
2866
|
627 @chapter Porting programs from @sc{Matlab} to Octave |
|
628 |
|
629 @cindex @sc{Matlab} compatibility |
|
630 @cindex Compatibility with @sc{Matlab} |
|
631 |
6612
|
632 People often ask |
|
633 |
2866
|
634 ``I wrote some code for @sc{Matlab}, and I want to get it running under |
|
635 Octave. Is there anything I should watch out for?'' |
|
636 |
6612
|
637 or alternatively |
|
638 |
|
639 ``I wrote some code in Octave, and want to share it with @sc{Matlab} |
|
640 users. Is there anything I should watch out for?'' |
|
641 |
|
642 which is not quite the same thing. There are still a number of |
|
643 differences between Octave and @sc{Matlab}, however in general |
|
644 differences between the two are considered as bugs. Octave might |
|
645 consider that the bug is in @sc{Matlab} and do nothing about it, but |
|
646 generally functionality is almost identical. If you find a difference |
|
647 between Octave behavior and @sc{Matlab}, then you should send a |
|
648 description of this difference (with code illustrating the difference, |
|
649 if possible) to @email{bug@@octave.org}. |
|
650 |
|
651 Furthermore, Octave adds a few syntactical extensions to Matlab that |
|
652 might cause some issues when exchanging files between Matlab and Octave |
|
653 users. As both Octave and @sc{Matlab} are under constant development the |
|
654 information in this section is subject to change at anytime. |
|
655 |
|
656 You should also look at the page |
|
657 @url{http://octave.sourceforge.net/packages.html} and |
|
658 @url{http://octave.sourceforge.net/doc/} that has a function reference |
|
659 that is up to date. You can use this function reference to see the |
|
660 number of octave function that are available and their @sc{Matlab} |
|
661 compatibility. |
|
662 |
|
663 The major differences between Octave 2.9.10 and @sc{Matlab} v7.3 are: |
|
664 |
|
665 @itemize @bullet |
|
666 @item Nested Functions |
|
667 |
|
668 Octave doesn't yet have nested functions. That if |
2866
|
669 |
6612
|
670 @example |
|
671 @group |
|
672 function y = foo (x) |
|
673 y = bar(x) |
|
674 function y = bar (x) |
|
675 y = @dots{}; |
|
676 end |
|
677 end |
|
678 @end group |
|
679 @end example |
|
680 |
|
681 There was discussion in Octave of having these even prior to @sc{Matlab}, |
|
682 and the decision was made not to have these in Octave at the time for |
|
683 compatibility. The above written with sub-functions functions would be |
|
684 |
|
685 @example |
|
686 @group |
|
687 function y = foo (x) |
|
688 y = bar(x) |
|
689 end |
|
690 function y = bar (x) |
|
691 y = @dots{}; |
|
692 end |
|
693 @end group |
|
694 @end example |
|
695 |
|
696 Now that @sc{Matlab} has recently introduced nested functions, Octave will |
|
697 probably have them soon as well. Till then nested functions in Octave |
|
698 are treated as sub-functions with the same scoping rules as |
|
699 sub-functions. |
|
700 |
|
701 The authors of Octave consider the nested function scoping rules of |
|
702 Matlab to be more problems than they are worth as they introduce |
|
703 diffiult to find bugs as inadvertantly modifying a variable in a |
|
704 nested function that is also used in the parent is particularly easy. |
|
705 |
|
706 @item Differences in core syntax |
|
707 |
|
708 There a few core @sc{Matlab} syntaxes that are not accepted by Octave, |
|
709 these being |
|
710 |
|
711 @itemize @bullet |
2866
|
712 @item |
6612
|
713 Some limitations on the use of function handles. The major difference is |
|
714 related to nested function scoping rules (as above) and there use with |
|
715 function handles. |
2866
|
716 |
|
717 @item |
6612
|
718 Some limitations of variable argument lists on the LHS of an expression, |
|
719 though the most common types are accepted. |
|
720 |
|
721 @item |
|
722 @sc{Matlab} object-oriented classes with overloading etc through the |
|
723 subasgn and "@@" directories is not treated by Octave. There is work to |
|
724 remove this restriction in the future. |
2866
|
725 |
|
726 @item |
6612
|
727 @sc{Matlab} private directories are not treated, though as for classes, |
|
728 this will change in the near future. This restriction alleviated by |
|
729 using addpath on the private directories, but this makes the private |
|
730 directories visible in the global scope. |
|
731 @end itemize |
|
732 |
|
733 @item Differences in core functions |
|
734 |
|
735 A large number of the @sc{Matlab} core functions (ie those that are in |
|
736 the core and not a toolbox) are implemented, and certainly all of the |
|
737 commonly used ones. There are a few functions that aren't implemented, |
|
738 for example condest or to do with specific missing Octave functionality |
|
739 (gui, dll, java, activex, dde, web, and serial functions). Some of the |
|
740 core functions have limitations that aren't in the @sc{Matlab} |
|
741 version. For example the interpN function can only do linear |
|
742 interpolation and not cubic spline, etc.. However the interp and interp2 |
|
743 function can. |
|
744 |
|
745 @item Just-In-Time compiler |
|
746 |
|
747 @sc{Matlab} includes a "Just-In-Time" compiler. This compiler allows the |
|
748 acceleration of for-loops in @sc{Matlab} to almost native performance with |
|
749 certain restrictions. The JIT must know the return type of all functions |
|
750 called in the loops and so you can't include user functions in the loop |
|
751 of JIT optimized loops. Octave doesn't have a JIT and so to some might |
|
752 seem slower than @sc{Matlab}. For this reason you must vectorize your code as |
|
753 much as possible. @sc{Matlab} themselves produces a good document discussing |
|
754 vectorization at |
|
755 @url{http://www.mathworks.com/support/tech-notes/1100/1109.html}. |
|
756 |
|
757 @item Compiler |
|
758 |
|
759 On a related point, there is no Octave compiler, and so you can't |
|
760 convert your Octave code into a binary for additional speed or |
|
761 distribution. There is an example of how to do this at |
|
762 @url{http://www.stud.tu-ilmenau.de/~rueckn/}, but this is a very early |
|
763 example code and would need lots of work to complete it. |
|
764 |
|
765 @item Graphic Handles |
|
766 |
|
767 Up to Octave 2.9.9 there was no support for graphic handles in Octave |
|
768 itself. There is in Octave 2.9.10 and later, and so the graphics between |
|
769 Octave and @sc{Matlab} are currently in the process of converging to a |
|
770 common interface. Note that the basic graphic handle stuff is in place |
|
771 in 2.9.10, but not graphics objects like "patch", "barseries", etc. |
|
772 |
|
773 @item GUI |
|
774 |
|
775 There is no @sc{Matlab} compatible GUI functions. There are a number of |
|
776 bindings from Octave to tcl/tk, vtk and zenity included in the |
|
777 octave-forge project (@url{http://octave.sourceforge.net}) for example |
|
778 that can be used for a GUI, but these are not @sc{Matlab} |
|
779 compatible. This might be an issue if you intend to exchange Octave code |
|
780 with @sc{Matlab} users. |
|
781 |
|
782 @item Simulink |
|
783 |
|
784 Octave itself includes no Simulink support. Typically the simulink |
|
785 models lag research and are less flexible, so shouldn't really be used |
|
786 in a research environment. However, some @sc{Matlab} users that try to use |
|
787 Octave complain about this lack. There is a similar package to simulink |
|
788 for the Octave and R projects available at @url{http://www.scicraft.org/} |
|
789 |
|
790 @item Mex-Files |
2866
|
791 |
6612
|
792 Octave includes an API to the matlab MEX interface. However, as MEX is |
|
793 an API to the internals of @sc{Matlab} and the internals of Octave differ to |
|
794 @sc{Matlab}, there is necessarily a manipulation of the data to convert from |
|
795 a MEX interface to the Octave equivalent. This is notable for all |
|
796 complex matrices, where matlab stores complex arrays as real and |
|
797 imaginary parts, whereas octave respects the C99/C++ standards of |
|
798 co-locating the real/imag parts in memory. Also due to the way matlab |
|
799 allows access to the arrays passed through a pointer, the MEX interface |
|
800 might require that copies of arrays (even non complex ones). There were |
|
801 some serious memory leaks in the MEX API in Octave up to version 2.9.9, |
|
802 and version 2.9.10 or later should be used if posible. |
|
803 |
|
804 @item Block comments |
|
805 |
|
806 @sc{Matlab} recently included the possibility to have block comments. With |
|
807 the "%@{" and "%@}" markers. Octave doesn't yet have block comments, but |
|
808 might in the future. |
|
809 |
|
810 @item Mat-File format |
|
811 |
|
812 There are some differences in the mat v5 file format accepted by |
|
813 Octave. @sc{Matlab} recently introduced the "-V7.3" save option which is |
|
814 an hdf5 format which is particularly useful for 64-bit platforms where |
|
815 the standard matlab format can not correctly save variables.. Octave |
|
816 accepts hdf5 files, but is not yet compatible with the "-v7.3" versions |
|
817 produced by @sc{Matlab}. |
|
818 |
|
819 Up to version 2.9.10, Octave can't load/save the inline or function |
|
820 handles saved in mat-files by @sc{Matlab} (though can in its own |
|
821 format). There is some work to fix this, but the @sc{Matlab} function handle |
|
822 format in mat-files is undocumented and this is therefore not easy to |
|
823 address. |
|
824 |
|
825 Finally, Some multi-byte unicode characters aren't yet treated in |
|
826 mat-files. |
|
827 |
|
828 @item Profiler |
|
829 |
|
830 Octave doesn't have a profiler. Though there is a patch for a flat |
|
831 profiler, that might become a real profiler sometime in the future. see |
|
832 the thread |
|
833 |
|
834 @url{http://www.cae.wisc.edu/pipermail/octave-maintainers/2007-January/001685.html} |
|
835 |
|
836 for more details |
|
837 |
|
838 @item Toolboxes |
|
839 |
|
840 Octave is a community project and so the toolboxes that exist are |
|
841 donated by those interested in them through the octave-forge website |
|
842 (@url{http://octave.sourceforge.net}). These might be lacking in certain |
|
843 functionality relative to the @sc{Matlab} toolboxes, and might not |
|
844 exactly duplicate the matlab functionality or interface. |
|
845 |
|
846 @item Short-circuit & and | operators |
|
847 |
|
848 The & and | operators in @sc{Matlab} short-circuit when included in an if |
|
849 statemant and not otherwise. Whereas in Octave only the && and || |
|
850 short circuit. This is due to the absence of && and || in @sc{Matlab} |
|
851 till recently. Note that this means that |
|
852 |
|
853 @example |
|
854 @group |
|
855 if (a | b) |
|
856 @dots{} |
|
857 end |
|
858 @end group |
|
859 @end example |
|
860 |
|
861 and |
|
862 |
|
863 @example |
|
864 @group |
|
865 t = a | b; |
|
866 if t |
|
867 @dots{} |
|
868 end |
|
869 @end group |
|
870 @end example |
|
871 |
|
872 are different in @sc{Matlab}. This is really a @sc{Matlab} bug, but |
|
873 there is too much code out there that relies on this behavior to change |
|
874 it. Prefer the || and && operators in if statements if possible. |
2866
|
875 |
6612
|
876 Note that the difference is also significant when either argument is a |
|
877 function with side effects or if the first argument is a scalar and the |
|
878 second argument is an empty matrix. For example, note the difference |
|
879 between |
|
880 |
|
881 @example |
|
882 @group |
|
883 t = 1 | []; ## results in [], so... |
|
884 if (t) 1, end ## in if ([]), this is false. |
|
885 @end group |
|
886 @end example |
|
887 |
|
888 and |
|
889 |
|
890 @example |
|
891 if (1 | []) 1, end ## short circuits so condition is true. |
|
892 @end example |
|
893 |
|
894 Another case that is documented in the @sc{Matlab} manuals is that |
|
895 |
|
896 @example |
|
897 @group |
|
898 t = [1, 1] | [1, 2, 3]; ## error |
|
899 if ([1, 1] | [1, 2, 3]) 1, end ## OK |
|
900 @end group |
|
901 @end example |
|
902 |
|
903 Also @sc{Matlab} requires the operands of && and || to be scalar values but |
|
904 Octave does not (it just applies the rule that for an operand to be |
|
905 considered true, every element of the object must be nonzero or |
|
906 logically true). |
|
907 |
|
908 Finally, note the inconsistence of thinking of the condition of an if |
|
909 statement as being equivalent to @code{all(X(:))} when @var{X} is a |
|
910 matrix. This is true for all cases EXCEPT empty matrices: |
|
911 |
|
912 @example |
|
913 @group |
|
914 if ([0, 1]) == if (all ([0, 1])) ==> i.e., condition is false. |
|
915 if ([1, 1]) == if (all ([1, 1])) ==> i.e., condition is true. |
|
916 @end group |
|
917 @end example |
|
918 |
|
919 However, |
|
920 |
|
921 @example |
|
922 if ([]) != if (all ([])) |
|
923 @end example |
|
924 |
|
925 because @code{all ([]) == 1} (because, despite the name, it is really |
|
926 returning true if none of the elements of the matrix are zero, and since |
|
927 there are no elements, well, none of them are zero). But, somewhere |
|
928 along the line, someone decided that if @code{([])} should be false. |
|
929 Mathworks probably thought it just looks wrong to have @code{[]} be true |
|
930 in this context even if you can use logical gymnastics to convince |
|
931 yourself that "all" the elements of a matrix that doesn't actually have |
|
932 any elements are nonzero. Octave however duplicates this behavior for if |
|
933 statements containing empty matrices. |
|
934 |
|
935 @item Octave extensions |
|
936 |
|
937 The extensions in Octave over @sc{Matlab} syntax are |
|
938 very useful, but might cause issues when sharing with @sc{Matlab} users. |
|
939 A list of the major extensions that should be avoided to be compatible |
|
940 with @sc{Matlab} are |
|
941 |
|
942 @itemize @bullet |
|
943 @item |
|
944 Comments in octave can be marked with "#". This allows POSIX |
|
945 systems to have the first line as "#! octave -q" and mark the script |
6653
|
946 itself executable. @sc{Matlab} doesn't have this feature due to the |
6612
|
947 absence of comments starting with "#" |
2866
|
948 |
6612
|
949 @item |
|
950 Code blocks like if, for, while, etc can be terminated with block |
|
951 specific terminations like "endif". @sc{Matlab} doesn't have this and |
|
952 all blocks must be terminated with "end" |
|
953 |
|
954 @item |
|
955 Octave has a lisp like unwind_protect block that allows blocks of |
|
956 code that terminate in an error to ensure that the variables that |
|
957 are touched are restored. You can do something similar with |
|
958 try/catch combined with rethrow(lasterror()) in @sc{Matlab}, however |
|
959 rethrow and lasterror were only just introduced in Octave and so |
|
960 aren't in 2.9.9, but are in 2.9.10. |
|
961 |
|
962 Note that using try/catch combined with rethrow(lasterror()) can not |
|
963 guarentee that global variables will be correctly reset, as it won't |
|
964 catch user interrupts with Ctrl-C. For example |
|
965 |
|
966 @example |
|
967 @group |
|
968 global a |
|
969 a = 1; |
|
970 try |
|
971 _a = a; |
|
972 a = 2 |
|
973 while true |
|
974 end |
|
975 catch |
|
976 fprintf ('caught interrupt\n'); |
|
977 a = _a; |
|
978 rethrow (lasterror()); |
|
979 end |
|
980 @end group |
|
981 @end example |
|
982 |
|
983 @noindent |
|
984 compared to |
|
985 |
|
986 @example |
|
987 @group |
|
988 global a |
|
989 a = 1; |
|
990 unwind_protect |
|
991 _a = a; |
|
992 a = 2 |
|
993 while true |
|
994 end |
|
995 unwind_protect_cleanup |
|
996 fprintf ('caught interrupt\n'); |
|
997 a = _a; |
|
998 end |
|
999 @end group |
|
1000 @end example |
|
1001 |
|
1002 Typing Ctrl-C in the first case returns the user directly to the |
|
1003 prompt, and the variable "a" is not reset to the save value. In the |
|
1004 second case the variable "a" is reset correctly. Therefore matlab |
|
1005 gives no save way of temporarily changing global variables. |
|
1006 |
|
1007 @item |
|
1008 Indexing can be applied to all objects in Octave and not just |
|
1009 variable. Therefore @code{sin(x)(1:10);} for example is perfectly valid |
|
1010 in Octave but not @sc{Matlab}. To do the same in @sc{Matlab} you must do |
|
1011 @code{y = sin(x); y = y([1:10]);} |
|
1012 |
|
1013 @item |
|
1014 Octave has the operators "++", "--", "-=", "+=", "*=", etc. As |
|
1015 @sc{Matlab} doesn't, if you are sharing code these should be avoided. |
|
1016 |
|
1017 @item |
|
1018 Strings in Octave can be denoted with double or single quotes. There is |
|
1019 a subtle difference between the two in that escaped characters like \n, |
|
1020 etc are interpreted in double quoted strings but not single quoted |
|
1021 strings. This difference is important on Windows platforms where the "\" |
|
1022 character is used in path names, and so single quoted strings should be |
|
1023 used in paths. @sc{Matlab} doesn't have double quoted strings and so |
|
1024 they should be avoided if the code will be transfered to a matlab user. |
|
1025 @end itemize |
|
1026 |
|
1027 @end itemize |
2866
|
1028 |
4830
|
1029 @node Index |
2866
|
1030 @appendix Concept Index |
|
1031 |
|
1032 @printindex cp |
|
1033 |
|
1034 @page |
|
1035 @contents |
|
1036 @bye |