Mercurial > octave
view doc/faq/Octave-FAQ.texi @ 6606:2c19eaa2c6f7
[project @ 2007-05-07 17:09:38 by jwe]
author | jwe |
---|---|
date | Mon, 07 May 2007 17:09:38 +0000 |
parents | cd06796e0ed6 |
children | 89f3a84a0da1 |
line wrap: on
line source
\input texinfo.tex @c -*-texinfo-*- @setfilename Octave-FAQ.info @settitle Frequently asked questions about Octave (with answers) @setchapternewpage off @direntry * Octave-FAQ: (Octave-FAQ). Frequently asked questions about Octave @end direntry @titlepage @title Octave FAQ @subtitle Frequently asked questions about Octave @subtitle April, 2007 @sp 1 @author John W. Eaton @page @end titlepage @ifnottex @node Top @top @unnumbered Preface @cindex FAQ for Octave, latest version @end ifnottex This is a list of frequently asked questions (FAQ) for Octave users. We are always looking for new questions (@emph{with} answers), better answers, or both. Please send suggestions to @email{bug@@octave.org}. If you have general questions about Octave, or need help for something that is not covered by the Octave manual or the FAQ, please use the @email{help@@octave.org} mailing list. This FAQ is intended to supplement, not replace, the Octave manual. Before posting a question to the @email{help@@octave.org} mailing list, you should first check to see if the topic is covered in the manual. @menu * What is Octave?:: * How can I cite Octave?:: * Series 2.9.N:: * Octave Features:: * Learning more about Octave:: * Getting Octave:: * Installation:: * Common problems:: * How do I ...?:: * MATLAB compatibility:: * Index:: @end menu @node What is Octave? @chapter What is Octave? Octave is a high-level interactive language, primarily intended for numerical computations that is mostly compatible with @sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks, Inc.} Octave can do arithmetic for real, complex or integer-valued scalars and matrices, solve sets of nonlinear algebraic equations, integrate functions over finite and infinite intervals, and integrate systems of ordinary differential and differential-algebraic equations. Octave uses the GNU readline library to handle reading and editing input. By default, the line editing commands are similar to the cursor movement commands used by GNU Emacs, and a vi-style line editing interface is also available. At the end of each session, the command history is saved, so that commands entered during previous sessions are not lost. The Octave distribution includes a 550+ page Texinfo manual. Access to the complete text of the manual is available via the help command @c really, the *complete* text? at the Octave prompt. @menu * Who develops Octave?:: * Why GNU Octave?:: * What version should I use?:: * On what platforms does Octave run?:: @end menu @node Who develops Octave? @section Who develops Octave? Discussions about writing the software that would eventually become Octave started in about 1988 with James B. Rawlings and John W. Eaton at the University of Texas. John W. Eaton was the original author of Octave, starting full-time development in February 1992. He is still the primary maintainer. The community of users/developers has in addition contributed some code and fuels the discussion on the mailing lists @email{help@@octave.org} (user forum), @email{bug@@octave.org} (bug reports), @email{maintainers@@octave.org} (development issues), and @email{octave-dev@@lists.sourceforge.net} (all things related to the Octave Forge repository of user-contributed functions). @node Why GNU Octave? @section Why GNU Octave? The GNU Project was launched in 1984 to develop a complete Unix-like operating system which is free software: the GNU system. GNU is a recursive acronym for ``GNU's Not Unix''; it is pronounced guh-noo, approximately like canoe. The Free Software Foundation (FSF) is the principal organizational sponsor of the GNU Project. Octave became GNU Octave in 1997 (beginning with version 2.0.6). This meant agreeing to consider Octave a part of the GNU Project and support the efforts of the FSF. However, Octave is not and has never been developed by the FSF. For more information about the GNU project, see @url{www.gnu.org}. @cindex FSF [Free Software Foundation] @cindex GNU [GNU's not unix] @node What version should I use? @section What version should I use? In general, you will find the latest version on @url{http://www.octave.org/download.html}. It is recommended to use the ``testing'' version of octave for general use, and the ``development'' version if you want the latest features. A list of user-visible changes since the last release is available in the file @file{NEWS}. The file @file{ChangeLog} in the source distribution contains a more detailed record of changes made since the last release. @node On what platforms does Octave run? @section On what platforms does Octave run? Octave runs on various Unices---at least Linux and Solaris, Mac OS X, Windows and anything you can compile it on. Binary distributions exist at least for Debian, Suse, Fedora and RedHat Linuxes (Intel and AMD CPUs, at least), for Mac Os X and Windows' 98, 2000 and XP. Two and three dimensional plotting is fully supported using gnuplot. The underlying numerical solvers are currently standard Fortran ones like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library of C++ classes. If possible, the Fortran subroutines are compiled with the system's Fortran compiler, and called directly from the C++ functions. If that's not possible, you can still compile Octave if you have the free Fortran to C translator f2c. Octave is also free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. @node How can I cite Octave? @chapter How can I cite Octave? Pointing to @url{http://www.octave.org} is good, because that gives people a direct way to find out more. If citation of a URL is not allowed by a publisher, or if you also want to point to a traditional reference, then you can cite the Octave manual: @example @group @@BOOK@{eaton:2002, author = "John W. Eaton", title = "GNU Octave Manual", publisher = "Network Theory Limited", year = "2002", isbn = "0-9541617-2-6" @} @end group @end example @node Series 2.9.N @chapter What's new in version series 2.9.N of Octave The 2.9.N series, started in March 2005, has enough new features to justify a major version number change. Version 2.9.10 is nearly as stable as the latest 2.1.N releases and stability should increase as one gets near version 3.0. Series 2.9.N brings @itemize @bullet @item integer types @item fixed point arithmetic @item sparse matrices @item Linear programming code based on GLPK @item 64-bit compilation support @item gzipped files and stream and consequently support of matlab v7 files @item better support for both msvc and mingw @item a fully compatiable MEX interface @item many many other minor features and compatibility changes @end itemize Here are some features that have been around since 2.1.NN @itemize @bullet @item NDarrays @item cells @end itemize @node Octave Features @chapter What features are unique to Octave? @menu * Functions defined on the command-line:: * Comments with #:: * Strings delimitted by double quotes ":: * Line continuation by backslash:: * Informative block closing:: * Coherent syntax:: * Exclamation mark as not operator:: @c * Short-circuit boolean operators:: * Increment and decrement operators:: * Unwind-protect:: * Built-in ODE and DAE solvers:: @end menu This section refers to Matlab 6,5.0 R 13 and Octave 2.9.10. @node Functions defined on the command-line @section Functions defined on the command-line Functions can be defined by entering code on the command line, a feature not supported by the other leading brand. For example, you may type: @example @group octave:1> function s = hello_string (to_who) > ## Say hello > if nargin<1, to_who = "World"; end > s = ["Hello ",\ > to_who]; > endfunction octave:2> hello_string ("Moon") ans = Hello Moon @end group @end example @node Comments with # @section Comments with # The pound character, @samp{#}, may be used to start comments, in addition to @samp{%}. See the previous example. The major advantage of this is that as @samp{#} is also a comment character for unix script files, any file that starts with a string like @samp{#! /usr/bin/octave -q} will be treated as an octave script and be executed by octave. @node Strings delimitted by double quotes " @section Strings delimitted by double quotes " The double quote, @samp{"}, may be used to delimit strings, in addition to the single quote @samp{'}. See the previous example. Also, double-quoted strings include backslash interpretation (like C++, C, and Perl) while single quoted are uninterpreted (like Matlab and Perl). @node Line continuation by backslash @section Line continuation by backslash Lines can be continued with a backslash, @samp{\}, in addition to three points @samp{@dots{}}. See the previous example. @node Informative block closing @section Informative block closing You may close @code{function}, @code{for}, @code{while}, @code{if}, @dots{} blocks with @code{endfunction}, @code{endfor}, @code{endwhile}, @dots{} keywords in addition to using @code{end}. As with Matlab, the @code{end} (or @code{endfunction}) keyword that marks the end of a function defined in a @file{.m} file is optional. @node Coherent syntax @section Coherent syntax Indexing other things than variables is possible, as in: @example @group octave:1> [3 1 4 1 5 9](3) ans = 4 octave:2> cos([0 pi pi/4 7])(3) ans = 0.70711 @end group @end example @node Exclamation mark as not operator @section Exclamation mark as not operator The exclamation mark '!' (aka ``Bang!'') is a negation operator, just like the tilde '~': @example @group octave:1> if ! strcmp (program_name, "octave"), > "It's an error" > else > "It works!" > end ans = It works! @end group @end example @node Increment and decrement operators @section Increment and decrement operators @cindex Increment operators @cindex Decrement operators @cindex Operators, increment @cindex Operators, decrement If you like the @samp{++}, @samp{+=} etc operators, rejoice! Octave includes the C-like increment and decrement operators @samp{++} and @samp{--} in both their prefix and postfix forms, in addition to @samp{+=}, @samp{-=}, @samp{*=}, @samp{/=}, @samp{^=}, @samp{.*=}, @samp{./=}, and @samp{.^=}. For example, to pre-increment the variable @var{x}, you would write @code{++@var{x}}. This would add one to @var{x} and then return the new value of @var{x} as the result of the expression. It is exactly the same as the expression @code{@var{x} = @var{x} + 1}. To post-increment a variable @var{x}, you would write @code{x++}. This adds one to the variable @var{x}, but returns the value that @var{x} had prior to incrementing it. For example, if @var{x} is equal to 2, the result of the expression @code{x++} is 2, and the new value of @var{x} is 3. For matrix and vector arguments, the increment and decrement operators work on each element of the operand. @node Unwind-protect @section Unwind-protect @cindex Unwind-protect Octave supports a limited form of exception handling modelled after the unwind-protect form of Lisp. The general form of an @code{unwind_protect} block looks like this: @example @group unwind_protect @var{body} unwind_protect_cleanup @var{cleanup} end_unwind_protect @end group @end example @noindent Where @var{body} and @var{cleanup} are both optional and may contain any Octave expressions or commands. The statements in @var{cleanup} are guaranteed to be executed regardless of how control exits @var{body}. The @code{unwind_protect} statement is often used to reliably restore the values of global variables that need to be temporarily changed. @node Built-in ODE and DAE solvers @section Built-in ODE and DAE solvers @cindex DASSL @cindex LSODE Octave includes LSODE and DASSL for solving systems of stiff ordinary differential and differential-algebraic equations. These functions are built in to the interpreter. @node Learning more about Octave @chapter What documentation exists for Octave? @menu * Documentation:: * Getting additional help:: * User community:: * Bug reports:: @end menu @node Documentation @section What documentation exists for Octave? @cindex Octave, documentation The Octave distribution includes a 550+ page manual that is also distributed under the terms of the GNU GPL. It is available on the web at @url{http://www.octave.org/docs.html} and you will also find there instructions on how to order a paper version. The complete text of the Octave manual is also available using the GNU Info system via the GNU Emacs, info, or xinfo programs, or by using the @samp{help -i} command to start the GNU info browser directly from the Octave prompt. If you have problems using this documentation, or find that some topic is not adequately explained, indexed, or cross-referenced, please send a bug report to @email{bug@@octave.org}. @node Getting additional help @section Getting additional help @cindex Additional help @cindex Mailing lists, help-octave If you can't find an answer to your question, the @email{help@@octave.org} mailing list is available for questions related to using, installing, and porting Octave that are not adequately answered by the Octave manual or by this document. @node User community @section User community To subscribe to the list, go to @url{www.octave.org/archive.html} and follow the link to the subscription page for the list. @strong{Please do not} send requests to be added or removed from the the mailing list, or other administrative trivia to the list itself. An archive of old postings to the help-octave mailing list is maintained on @url{http://www.octave.org/archive.html}. You will also find some user advice and code spread over the web. Good starting points are the Octave Wiki @url{http://wiki.octave.org} and Octave-Forge @url{htt://octave.sourceforge.net} @node Bug reports @section I think I have found a bug in Octave. @cindex Bug in Octave, newly found ``I think I have found a bug in Octave, but I'm not sure. How do I know, and who should I tell?'' @cindex Manual, for Octave First, see the section on bugs and bug reports in the Octave manual. When you report a bug, make sure to describe the type of computer you are using, the version of the operating system it is running, and the version of Octave that you are using. Also provide enough code so that the Octave maintainers can duplicate your bug. If you have Octave working at all, the easiest way to do this is to use the Octave function @code{bug_report}. When you execute this function, Octave will prompt you for a subject and then invoke the editor on a file that already contains all the configuration information. When you exit the editor, Octave will mail the bug report for you (in a unix-like operating system). @cindex Octave bug report @cindex Mailing lists, bug-octave If for some reason you cannot use Octave's @code{bug_report} function, mail your bug report to @email{bug@@octave.org}. Your message needs to include enough information to allow the maintainers of Octave to fix the bug. Please read the section on bugs and bug reports in the Octave manual for a list of things that should be included in every bug report. @node Getting Octave @chapter Getting Octave @menu * Source code:: * Pre-compiled binary packages:: * Octave for other platforms:: @end menu @node Source code @section Source code @cindex Source code Source code is available on the Octave development site, where you are sure to get the latest version. @itemize @bullet @item @url{http://www.octave.org/download.html} @item @url{ftp://ftp.octave.org/pub/octave/} @end itemize Since Octave is distrubted under the terms of the GPL, you can get Octave from a friend who has a copy, by anonymous FTP, or by ordering a tape or CD-ROM from the Free Software Foundation (FSF). @node Pre-compiled binary packages @section Pre-compiled binary packages @cindex Pre-compiled binary packages @cindex Binaries The Octave project does not distribute binary packages, but other projects do. For an up-to-date listing of packagers, see: @itemize @bullet @item @url{http://www.octave.org/download.html} @item @url{http://wiki.octave.org/wiki.pl?CategoryInstall} @end itemize As of today, Octave binaries are available at least on Debian, RedHat, Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP. @node Octave for other platforms @section How do I get a copy of Octave for (some other platform)? @cindex VMS support @cindex VAX @cindex MS-DOS support @cindex Windows support @cindex DJGPP @cindex EMX @cindex OS/2 support Octave currently runs on Unix-like systems, Mac OS X, and Windows (using the Cygwin tools from Red Hat). It should be possible to make Octave work on other systems as well. If you are interested in porting Octave to other systems, please contact @email{bug@@octave.org}. @c @menu @c * Octave for Unix:: @c * Octave for other platforms:: @c * latest versions:: @c @end menu @c @cindex Octave, ordering @c @cindex Octave, getting a copy @node Installation @chapter Installation Issues and Problems @cindex Octave, building Octave 2.9.10 requires approximately 800MB of disk storage to unpack and compile from source (considerably less if you don't compile with debugging symbols). Once installed, Octave requires approximately 200MB of disk space (again, considerably less if you don't compile with debugging symbols). @menu * What else do I need?:: * Other C++ compilers?:: @end menu @node What else do I need? @section What else do I need? @cindex GNU gcc @cindex GNU g++ @cindex libg++ @cindex GNU Make @cindex Flex @cindex GNU Bison To compile Octave, you will need a recent version of GNU Make. You will also need GCC 3.3 or later, although GCC 4.1 or later is recommended. @strong{You must have GNU Make to compile octave}. Octave's Makefiles use features of GNU Make that are not present in other versions of make. GNU Make is very portable and easy to install. @node Other C++ compilers? @section Can I compile Octave with another C++ compiler? Yes, but development is done primarily with GCC, so you may hit some incompatibilities. Octave is intended to be portable to any standard conforming compiler. If you have difficulties that you think are bugs, please report them to the @email{bug@@octave.org} mailing list, or ask for help on the @email{help@@octave.org} mailing list. @node Common problems @chapter Common problems This list is probably far too short. Feel free to suggest additional questions (preferably with answers!) @itemize @bullet @item Octave takes a long time to find symbols. Octave uses the @code{genpath} function to recursively add directories to the list of directories searched for function files. Check the list of directories with the @code{path} command. If the path list is very long check your use of the @code{genpath} function. @end itemize @node How do I ...? @chapter How do I ...? @menu * How do I set the number of displayed decimals?:: @end menu @cindex Tips and tricks @cindex How do I @dots{} ? @node How do I set the number of displayed decimals? @section How do I set the number of displayed decimals? @example @group octave:1> format long octave:2> pi pi = 3.14159265358979 octave:3> format short octave:4> pi pi = 3.1416 @end group @end example @node MATLAB compatibility @chapter Porting programs from @sc{Matlab} to Octave @cindex @sc{Matlab} compatibility @cindex Compatibility with @sc{Matlab} ``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: @enumerate @item Irrelevant. @item Known differences, perhaps configurable with a user preference variable. @item Unknown differences. @end enumerate The first category, irrelevant differences, do not affect computations and most likely do not affect the execution of function files. 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. 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}. @node Index @appendix Concept Index @printindex cp @page @contents @bye