Mercurial > hg > octave-avbm
changeset 6612:89f3a84a0da1
[project @ 2007-05-09 21:17:45 by jwe]
author | jwe |
---|---|
date | Wed, 09 May 2007 21:17:45 +0000 |
parents | 9197bb0a2738 |
children | b85dd243601d |
files | doc/ChangeLog doc/faq/Octave-FAQ.texi |
diffstat | 2 files changed, 388 insertions(+), 19 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2007-05-09 David Bateman <dbateman@free.fr> + + * faq/Octave-FAQ.texi: Update compatibility section. + 2007-04-27 David Bateman <dbateman@free.fr> * Makefile.in (EXAMPLE_FILES_NODIR): Add mycell.c, myfeval.c,
--- a/doc/faq/Octave-FAQ.texi +++ b/doc/faq/Octave-FAQ.texi @@ -629,37 +629,402 @@ @cindex @sc{Matlab} compatibility @cindex Compatibility with @sc{Matlab} +People often ask + ``I wrote some code for @sc{Matlab}, and I want to get it running under Octave. Is there anything I should watch out for?'' -The differences between Octave and @sc{Matlab} typically fall into one of -three categories: +or alternatively + +``I wrote some code in Octave, and want to share it with @sc{Matlab} +users. Is there anything I should watch out for?'' + +which is not quite the same thing. There are still a number of +differences between Octave and @sc{Matlab}, however in general +differences between the two are considered as bugs. Octave might +consider that the bug is in @sc{Matlab} and do nothing about it, but +generally functionality is almost identical. If you find a difference +between Octave behavior and @sc{Matlab}, then you should send a +description of this difference (with code illustrating the difference, +if possible) to @email{bug@@octave.org}. + +Furthermore, Octave adds a few syntactical extensions to Matlab that +might cause some issues when exchanging files between Matlab and Octave +users. As both Octave and @sc{Matlab} are under constant development the +information in this section is subject to change at anytime. + +You should also look at the page +@url{http://octave.sourceforge.net/packages.html} and +@url{http://octave.sourceforge.net/doc/} that has a function reference +that is up to date. You can use this function reference to see the +number of octave function that are available and their @sc{Matlab} +compatibility. + +The major differences between Octave 2.9.10 and @sc{Matlab} v7.3 are: + +@itemize @bullet +@item Nested Functions + +Octave doesn't yet have nested functions. That if -@enumerate +@example +@group +function y = foo (x) + y = bar(x) + function y = bar (x) + y = @dots{}; + end +end +@end group +@end example + +There was discussion in Octave of having these even prior to @sc{Matlab}, +and the decision was made not to have these in Octave at the time for +compatibility. The above written with sub-functions functions would be + +@example +@group +function y = foo (x) + y = bar(x) +end +function y = bar (x) + y = @dots{}; +end +@end group +@end example + +Now that @sc{Matlab} has recently introduced nested functions, Octave will +probably have them soon as well. Till then nested functions in Octave +are treated as sub-functions with the same scoping rules as +sub-functions. + +The authors of Octave consider the nested function scoping rules of +Matlab to be more problems than they are worth as they introduce +diffiult to find bugs as inadvertantly modifying a variable in a +nested function that is also used in the parent is particularly easy. + +@item Differences in core syntax + +There a few core @sc{Matlab} syntaxes that are not accepted by Octave, +these being + +@itemize @bullet @item -Irrelevant. +Some limitations on the use of function handles. The major difference is +related to nested function scoping rules (as above) and there use with +function handles. @item -Known differences, perhaps configurable with a user preference variable. +Some limitations of variable argument lists on the LHS of an expression, +though the most common types are accepted. + +@item +@sc{Matlab} object-oriented classes with overloading etc through the +subasgn and "@@" directories is not treated by Octave. There is work to +remove this restriction in the future. @item -Unknown differences. -@end enumerate +@sc{Matlab} private directories are not treated, though as for classes, +this will change in the near future. This restriction alleviated by +using addpath on the private directories, but this makes the private +directories visible in the global scope. +@end itemize + +@item Differences in core functions + +A large number of the @sc{Matlab} core functions (ie those that are in +the core and not a toolbox) are implemented, and certainly all of the +commonly used ones. There are a few functions that aren't implemented, +for example condest or to do with specific missing Octave functionality +(gui, dll, java, activex, dde, web, and serial functions). Some of the +core functions have limitations that aren't in the @sc{Matlab} +version. For example the interpN function can only do linear +interpolation and not cubic spline, etc.. However the interp and interp2 +function can. + +@item Just-In-Time compiler + +@sc{Matlab} includes a "Just-In-Time" compiler. This compiler allows the +acceleration of for-loops in @sc{Matlab} to almost native performance with +certain restrictions. The JIT must know the return type of all functions +called in the loops and so you can't include user functions in the loop +of JIT optimized loops. Octave doesn't have a JIT and so to some might +seem slower than @sc{Matlab}. For this reason you must vectorize your code as +much as possible. @sc{Matlab} themselves produces a good document discussing +vectorization at +@url{http://www.mathworks.com/support/tech-notes/1100/1109.html}. + +@item Compiler + +On a related point, there is no Octave compiler, and so you can't +convert your Octave code into a binary for additional speed or +distribution. There is an example of how to do this at +@url{http://www.stud.tu-ilmenau.de/~rueckn/}, but this is a very early +example code and would need lots of work to complete it. + +@item Graphic Handles + +Up to Octave 2.9.9 there was no support for graphic handles in Octave +itself. There is in Octave 2.9.10 and later, and so the graphics between +Octave and @sc{Matlab} are currently in the process of converging to a +common interface. Note that the basic graphic handle stuff is in place +in 2.9.10, but not graphics objects like "patch", "barseries", etc. + +@item GUI + +There is no @sc{Matlab} compatible GUI functions. There are a number of +bindings from Octave to tcl/tk, vtk and zenity included in the +octave-forge project (@url{http://octave.sourceforge.net}) for example +that can be used for a GUI, but these are not @sc{Matlab} +compatible. This might be an issue if you intend to exchange Octave code +with @sc{Matlab} users. + +@item Simulink + +Octave itself includes no Simulink support. Typically the simulink +models lag research and are less flexible, so shouldn't really be used +in a research environment. However, some @sc{Matlab} users that try to use +Octave complain about this lack. There is a similar package to simulink +for the Octave and R projects available at @url{http://www.scicraft.org/} + +@item Mex-Files -The first category, irrelevant differences, do not affect computations -and most likely do not affect the execution of function files. +Octave includes an API to the matlab MEX interface. However, as MEX is +an API to the internals of @sc{Matlab} and the internals of Octave differ to +@sc{Matlab}, there is necessarily a manipulation of the data to convert from +a MEX interface to the Octave equivalent. This is notable for all +complex matrices, where matlab stores complex arrays as real and +imaginary parts, whereas octave respects the C99/C++ standards of +co-locating the real/imag parts in memory. Also due to the way matlab +allows access to the arrays passed through a pointer, the MEX interface +might require that copies of arrays (even non complex ones). There were +some serious memory leaks in the MEX API in Octave up to version 2.9.9, +and version 2.9.10 or later should be used if posible. + +@item Block comments + +@sc{Matlab} recently included the possibility to have block comments. With +the "%@{" and "%@}" markers. Octave doesn't yet have block comments, but +might in the future. + +@item Mat-File format + +There are some differences in the mat v5 file format accepted by +Octave. @sc{Matlab} recently introduced the "-V7.3" save option which is +an hdf5 format which is particularly useful for 64-bit platforms where +the standard matlab format can not correctly save variables.. Octave +accepts hdf5 files, but is not yet compatible with the "-v7.3" versions +produced by @sc{Matlab}. + +Up to version 2.9.10, Octave can't load/save the inline or function +handles saved in mat-files by @sc{Matlab} (though can in its own +format). There is some work to fix this, but the @sc{Matlab} function handle +format in mat-files is undocumented and this is therefore not easy to +address. + +Finally, Some multi-byte unicode characters aren't yet treated in +mat-files. + +@item Profiler + +Octave doesn't have a profiler. Though there is a patch for a flat +profiler, that might become a real profiler sometime in the future. see +the thread + +@url{http://www.cae.wisc.edu/pipermail/octave-maintainers/2007-January/001685.html} + +for more details + +@item Toolboxes + +Octave is a community project and so the toolboxes that exist are +donated by those interested in them through the octave-forge website +(@url{http://octave.sourceforge.net}). These might be lacking in certain +functionality relative to the @sc{Matlab} toolboxes, and might not +exactly duplicate the matlab functionality or interface. + +@item Short-circuit & and | operators + +The & and | operators in @sc{Matlab} short-circuit when included in an if +statemant and not otherwise. Whereas in Octave only the && and || +short circuit. This is due to the absence of && and || in @sc{Matlab} +till recently. Note that this means that + +@example +@group + if (a | b) + @dots{} + end +@end group +@end example + +and + +@example +@group + t = a | b; + if t + @dots{} + end +@end group +@end example + +are different in @sc{Matlab}. This is really a @sc{Matlab} bug, but +there is too much code out there that relies on this behavior to change +it. Prefer the || and && operators in if statements if possible. -The differences of the second category are usually because the authors -of Octave decided on a better (subjective) implementation than the way -@sc{Matlab} works. To make Octave more @sc{Matlab}-compatible, use the -command line option @samp{--traditional} (though really, with the latest -2.9.N version, most of the things that the @samp{--traditional} option -does are just cosmetic. +Note that the difference is also significant when either argument is a +function with side effects or if the first argument is a scalar and the +second argument is an empty matrix. For example, note the difference +between + +@example +@group + t = 1 | []; ## results in [], so... + if (t) 1, end ## in if ([]), this is false. +@end group +@end example + +and + +@example + if (1 | []) 1, end ## short circuits so condition is true. +@end example + +Another case that is documented in the @sc{Matlab} manuals is that + +@example +@group + t = [1, 1] | [1, 2, 3]; ## error + if ([1, 1] | [1, 2, 3]) 1, end ## OK +@end group +@end example + +Also @sc{Matlab} requires the operands of && and || to be scalar values but +Octave does not (it just applies the rule that for an operand to be +considered true, every element of the object must be nonzero or +logically true). + +Finally, note the inconsistence of thinking of the condition of an if +statement as being equivalent to @code{all(X(:))} when @var{X} is a +matrix. This is true for all cases EXCEPT empty matrices: + +@example +@group + if ([0, 1]) == if (all ([0, 1])) ==> i.e., condition is false. + if ([1, 1]) == if (all ([1, 1])) ==> i.e., condition is true. +@end group +@end example + +However, + +@example + if ([]) != if (all ([])) +@end example + +because @code{all ([]) == 1} (because, despite the name, it is really +returning true if none of the elements of the matrix are zero, and since +there are no elements, well, none of them are zero). But, somewhere +along the line, someone decided that if @code{([])} should be false. +Mathworks probably thought it just looks wrong to have @code{[]} be true +in this context even if you can use logical gymnastics to convince +yourself that "all" the elements of a matrix that doesn't actually have +any elements are nonzero. Octave however duplicates this behavior for if +statements containing empty matrices. + +@item Octave extensions + +The extensions in Octave over @sc{Matlab} syntax are +very useful, but might cause issues when sharing with @sc{Matlab} users. +A list of the major extensions that should be avoided to be compatible +with @sc{Matlab} are + +@itemize @bullet +@item +Comments in octave can be marked with "#". This allows POSIX +systems to have the first line as "#! octave -q" and mark the script +itself executable. @sc{Matlab} doesn't have this feature due the the +absence of comments starting with "#" -The third category of differences is (hopefully) shrinking. If you find -a difference between Octave behavior and @sc{Matlab}, then you should send a -description of this difference (with code illustrating the difference, -if possible) to @email{bug@@octave.org}. +@item +Code blocks like if, for, while, etc can be terminated with block +specific terminations like "endif". @sc{Matlab} doesn't have this and +all blocks must be terminated with "end" + +@item +Octave has a lisp like unwind_protect block that allows blocks of +code that terminate in an error to ensure that the variables that +are touched are restored. You can do something similar with +try/catch combined with rethrow(lasterror()) in @sc{Matlab}, however +rethrow and lasterror were only just introduced in Octave and so +aren't in 2.9.9, but are in 2.9.10. + +Note that using try/catch combined with rethrow(lasterror()) can not +guarentee that global variables will be correctly reset, as it won't +catch user interrupts with Ctrl-C. For example + +@example +@group + global a + a = 1; + try + _a = a; + a = 2 + while true + end + catch + fprintf ('caught interrupt\n'); + a = _a; + rethrow (lasterror()); + end +@end group +@end example + +@noindent +compared to + +@example +@group + global a + a = 1; + unwind_protect + _a = a; + a = 2 + while true + end + unwind_protect_cleanup + fprintf ('caught interrupt\n'); + a = _a; + end +@end group +@end example + +Typing Ctrl-C in the first case returns the user directly to the +prompt, and the variable "a" is not reset to the save value. In the +second case the variable "a" is reset correctly. Therefore matlab +gives no save way of temporarily changing global variables. + +@item +Indexing can be applied to all objects in Octave and not just +variable. Therefore @code{sin(x)(1:10);} for example is perfectly valid +in Octave but not @sc{Matlab}. To do the same in @sc{Matlab} you must do +@code{y = sin(x); y = y([1:10]);} + +@item +Octave has the operators "++", "--", "-=", "+=", "*=", etc. As +@sc{Matlab} doesn't, if you are sharing code these should be avoided. + +@item +Strings in Octave can be denoted with double or single quotes. There is +a subtle difference between the two in that escaped characters like \n, +etc are interpreted in double quoted strings but not single quoted +strings. This difference is important on Windows platforms where the "\" +character is used in path names, and so single quoted strings should be +used in paths. @sc{Matlab} doesn't have double quoted strings and so +they should be avoided if the code will be transfered to a matlab user. +@end itemize + +@end itemize @node Index @appendix Concept Index