FAQ: Difference between revisions

This is a list of frequently asked questions (FAQ) for GNU Octave users.

<div class="tocinline">__TOC__</div>

Octave became GNU Octave in 1997 (beginning with [[Release History|version 2.0.6]]).  This meant agreeing to consider Octave a part of the GNU Project and support the efforts of the FSF.  A big part of this effort is to adhere to the [https://www.gnu.org/prep/standards/standards.html GNU coding standards] and to benefit from GNU's infrastructure (e.g. [https://hg.savannah.gnu.org/hgweb/octave/ code hosting] and [http://bugs.octave.org bug tracking]).  Additionally, Octave receives [https://my.fsf.org/donate/working-together/octave sponsorship] from the FSF's Working Together fund.  However, Octave is not and has never been developed by the FSF.

Octave is free software and does not legally bind you to cite it.  However, we have invested a lot of time and effort in creating GNU Octave, and we would appreciate if you would cite if you used.  To cite GNU Octave in publications use:

Note that there are two reasons for citing the software used.  One is giving recognition to the work done by others which we already addressed.  The other is giving details on the system used so that experiments can be replicated.  For this, you should cite the version of Octave and all packages used (you can get this information using the <code>ver</code> command), as well as any details of your setup as part of your Methods.  In addition, you should make your source available.  See [http://software.ac.uk/so-exactly-what-software-did-you-use How to cite and describe software] for more details and an in depth discussion.

=Licensing issues=

That does not apply to GNU Octave, therefore the usage is in general prohibited.  It should suffice — although interpretations of this vary — to contact the author directly to send you the code personally (maybe released under a free license), or download the code from the author's own website, if available. [[Asking_for_package_to_be_released_under_GPL:_examples|Some examples of letters/email sent to authors for that purpose]].

See the [http://hg.savannah.gnu.org/hgweb/octave/file/tip/NEWS NEWS file] on the development branch.

* Many improvements to native OpenGL plotting

* ARPACK now distributed with Octave

* FTP objects

* Function handles aware of overloaded functions

* Matlab-style ignoring of output arguments using {{Codeline|~}}

* Sparse matrix indexing has been rewritten for speed

* The pkg command now accepts a -forge option to pull packages directly from Octave-forge

* a fully compatible MEX interface

* imwrite and imread (based on the GraphicsMagick library)

For full details on older releases, see:

* [http://hg.savannah.gnu.org/hgweb/octave/file/83792dd9bcc1/etc/NEWS.3 NEWS.3] for the 3.X.Y series

Do not do it!  Really, there is no reason to do this.  Octave has many

remember that your programs still need to load the packages they require.

==How do I execute an Octave script?==

If you call the script from the shell and it's plotting, please note [[#When I try plotting from a script, why am I not seeing anything?|how to plot when running a script from the shell]].

==How do I erase a figure?==  

==How do I call an octave function from C++?==

  #include <octave/oct.h>

  Matrix unis(f_ret(0).matrix_value());

  #!/bin/awk -f

Look at functions like exist, file_in_path.. and the other functions that their descriptions point to.

'''This only works with gnuplot as graphics_toolkit, NOT with fltk. See [https://savannah.gnu.org/bugs/?33180 Bug#33180]'''

   set(0, 'defaultfigurevisible', 'off');

Octave's default numerical type is IEEE 754 doubles, a.k.a. hardware floats. This type has 52 bits of precision or about 16 decimal digits. It's implemented in your computer's hardware, in your CPU, so it's '''fast'''. This type is assumed throughout for Octave's calculations.

<syntaxhighlight lang="Octave">uint64(18446744073709551610);</syntaxhighlight>

<syntaxhighlight lang="Octave">uint64(999999999999999) * 10000</syntaxhighlight>

There are no plans to support running P-files produced by Matlab in Octave.

=Common problems=

By default Octave is set to pass its screen output through a pager (usually the default pager is "less") which allows

things such as navigating through the output with arrow keys or searching for text or regular expressions within the output.

==When I try plotting from a script, why am I not seeing anything?==

* Fedora: {{Codeline|octave-devel}}

Please be more specific. What is the latest version, according to you? If you mean the latest released version, be aware that you may still have an older version due to whatever distribution method you're using. There may be a newer version available that you're not aware of due to the distribution method you're using to get Octave, and in most cases, there is a way to get a newer version via your distribution method (see other wiki pages for [[Octave_for_GNU/Linux|GNU/Linux]], [[Octave_for_MacOS_X|Mac OSX]], and [[Octave_for_Windows|Windows]]).

If your problem truly persists with the latest version, as indicated [http://www.gnu.org/software/octave/download.html here], then by all means report a bug or ask for help, but don't be surprised if volunteers are less inclined to help you with a problem that only exists in an older version of Octave.

Floating point arithmetic is an approximation '''in binary''' to arithmetic on real or complex numbers. Just like you cannot represent 1/3 exactly in decimal arithmetic (0.333333 is only a rough approximation to 1/3), you cannot represent some fractions like <math>1/10</math> exactly in base 2. In binary, the representation to one tenth is <math>0.0\overline{0011}_b</math> where the bar indicates that it repeats infinitely (like how <math>1/6 = 0.1\overline{6}_d</math> in decimal). Because this infinite repetition cannot be represented exactly with a finite number of digits, rounding errors occur for values that appear to be exact in decimal but are in fact approximations in binary, such as for example how 0.3 - 0.2 - 0.1 is not equal to zero.

To learn more about floating point arithmetic, consult [http://en.wikipedia.org/wiki/Floating_point_arithmetic its Wikipedia article] or the classical reference [http://floating-point-gui.de/ What Every Computer Scientist Should Know About Floating Point Arithmetic].

You have probably forgotten to load the package. Use {{Codeline|pkg load package-name}} to load it. Most packages are no longer loaded automatically to avoid surprises. See reasoning on related FAQ [[FAQ#How_do_I_install_all_Octave_packages.3F|how do I install all Octave packages]]. If you want a specific package to be loaded by default at startup, consider adding the {{Codeline|pkg load}} command on your {{path|[[.octaverc]]}} file.

Some windows users with integrated Intel GPUs have reported missing lines when printing with an OpenGL toolkit like FLTK or Qt. {{bug|42534}}

See also https://www.opengl.org/wiki/FAQ#Why_is_my_GL_version_only_1.4_or_lower.3F

If the Qt graphics toolkit is used and "plot" is used for the first time, the fontconfig scanner searches the font directory to build a font cache. This can take up to 3min on slow CPUs. See {{bug|45458}}

People often ask

<blockquote>

</blockquote>

<blockquote>

</blockquote>

You should also look at the pages http://octave.sourceforge.net/packages.php and http://octave.sourceforge.net/docs.html that have a function reference that is up to date. You can use this function reference to see the number of octave functions that are available and their Matlab compatibility.

Octave has limited support for nested functions. That is

The authors of Octave consider the nested function scoping rules of Matlab to be more problems than they are worth as they introduce difficult to find bugs as inadvertently modifying a variable in a nested function that is also used in the parent is particularly easy for those not attentive to detail.

There are a few core Matlab syntaxes that are not accepted by Octave, these being

* Matlab classdef object oriented programming is not yet supported, though work is underway in a branch of the development tree.

A large number of the 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, usually 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 Matlab version. For example the sprandn function can not force a particular condition number for the matrix like Matlab can. Another example is that testing and the runtests function work differently in Matlab and Octave.

Matlab includes a "Just-In-Time" compiler. This compiler allows the acceleration of for-loops in 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 Matlab. For this reason you must vectorize your code as much as possible. The MathWorks themselves have a good document discussing vectorization at http://www.mathworks.com/support/tech-notes/1100/1109.html.

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 have been several aborted attempts at creating an Octave compiler. Should the JIT compiler above ever be implemented, an Octave compiler should be more feasible.

Up to Octave 2.9.9 there was no support for graphic handles in Octave itself. In the 3.2.N versions of Octave and beyond, the support for graphics handles is converging towards full compatibility. The patch function is currently limited to 2-D patches, due to an underlying limitation in gnuplot, but the experimental OpenGL backend is starting to see an implementation of 3-D patches.

There are no Matlab compatible GUI functions yet.  This might be an issue if you intend to exchange Octave code with Matlab users. There are a number of bindings from Octave to {{Forge|tcl-octave|Tcl/Tk}}, [http://octaviz.sourceforge.net/index.php? VTK] and {{Forge|zenity}} for example, that can be used for a GUI, but these are not Matlab compatible. Work on a Matlab compatible GUI is in an alpha stage in the QtHandles project, which may form part of a future release of Octave.

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 Matlab users that try to use Octave complain about this lack.

Octave includes an API to the Matlab MEX interface. However, as MEX is an API to the internals of Matlab and the internals of Octave differ from 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 copies of arrays (even non complex ones).

Block comments denoted by {{Codeline|#{}} and {{Codeline|#&#125;}}  markers (or {{Codeline|%{}} and {{Codeline|%&#125;}}) are supported by Octave with some limitations. The major limitation is that block comments are not supported within [] or {}.

There are some differences in the mat v5 file format accepted by Octave. 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 Matlab.

Finally, some multi-byte Unicode characters aren't yet treated in mat-files.

Thanks to Daniel Kraft's 2011 Google Summer of Code project, Octave has a profiler since version 3.6.0. However, at the moment it only produces text output and has its own makeshift interface for hierarchical profiling.

Octave is a community project and so the toolboxes that exist are donated by those interested in them through [[Octave Forge]]. These might be lacking in certain functionality relative to the Matlab toolboxes, and might not exactly duplicate the Matlab functionality or interface.

The {{Codeline|&}} and {{Codeline|&#124;}} operators in Matlab short-circuit when included in a condition (e.g. an {{Codeline|if}} or {{Codeline|while}} statement) and not otherwise. In Octave only the {{Codeline|&&}} and {{Codeline|&#124;&#124;}} short circuit. Note that this means that

             end

             do_braindead_shortcircuit_evaluation(1)

because, despite the name, the {{Codeline|all}} 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. This is an example of [http://en.wikipedia.org/wiki/Vacuous_truth vacuous truth]. But, somewhere along the line, someone decided that {{Codeline|if ([])}} should be false. Mathworks probably thought it just looks wrong to have {{Codeline|[]}} be true in this context even if you can use logical gymnastics to convince yourself that "all" the elements of an empty matrix are nonzero. Octave however duplicates this behavior for {{Codeline|if}} statements containing empty matrices.

Matlab's solvers as used by the operators mldivide (\) and mrdivide (/), use a different approach than Octave's in the case of singular, under-, or over-determined matrices. In the case of a singular matrix, Matlab returns the result given by the LU decomposition, even though the underlying solver has flagged the result as erroneous. Octave has made the choice of falling back to a minimum norm solution of matrices that have been flagged as singular which arguably is a better result for these cases.

Since the mldivide (\) and mrdivide (/) operators are often part of a more complex expression, where there is no room to react to warnings or flags, it should prefer intelligence (robustness) to speed, and so the Octave developers are firmly of the opinion that Octave's approach for singular, under- and over-determined matrices is a better choice than Matlab's.

The extensions in Octave over MATLAB syntax are very useful, but might cause issues when sharing with Matlab users. A list of the major extensions that should be avoided to be compatible with Matlab are:

Character strings in Octave can be denoted with double or single quotes. There is a subtle difference between the two in that escaped characters like {{Codeline|\n}} (newline), {{Codeline|\t}} (tab), etc are interpreted in double quoted strings but not single quoted strings. This difference is important on Windows platforms where the {{Codeline|\}} character is used in path names, and so single quoted strings should be used in paths. MATLAB doesn't have double quoted strings and so they should be avoided if the code will be transferred to a MATLAB user.

=[https://en.wikipedia.org/wiki/Graphical_user_interface GUI]=

This is one of those times where the best documentation is to read the existing code.  We have three different toolkits in Octave now, so there are some examples to draw from.