Octave API

Information for Users

GNU Octave is a high-level programming language for numerical computing, which is specialized on applications with vectors and matrices. Advanced techniques like broadcasting of values and vectorization of functions make it easy to do computations on a large number of values. Programs written for MATLAB can usually run in Octave with no or only minor changes.

Download (Octave if free software): http://www.gnu.org/software/octave/download.html

Installation

The VIBes client-api for Octave can be installed as follows:

• Either from the VIBes release, in Octave navigate to the download folder and execute pkg install vibes-X.X.X.tar.gz
• or from Octave-Forge: in Octave execute pkg install -forge vibes
• or from source: run make -C client-api/Octave install in the git workspace.

Usage

Before usage, the Octave package must be loaded, which adds the functions to the search path. Execute pkg load vibes in Octave. Also you want to launch the VIBes viewer to see the results. After loading the package, the functions can be used like follows:

pkg load vibes
vibes.beginDrawing
vibes.drawBox (0, 1, 2, 3)
vibes.endDrawing

Integration of interval arithmetic packages

The function vibes.drawBox and vibes.drawBoxes can be used together with interval data types from the following Octave packages:

• the free Octave-Forge interval package, which is also compliant to IEEE Std 1788-2015, IEEE standard for interval arithmetic
• the proprietary INTLAB toolbox for Octave

pkg load vibes interval
vibes.beginDrawing
x = infsupdec ("[0, 3]")
y = sin (x) + 42
vibes.drawBox (x, y, "blue")
vibes.endDrawing

Information for Developers

The VIBes client API for Octave comprises the following parts. A big advantages from the chosen architecture is that communication with the VIBes viewer is handled by the already existing C++ client API.

  ,--------.  Octave API  ,----------.  VIBes  C++  ,--------------.
  | Octave | ------------ | oct-file | ------------ | VIBes viewer |
  `--------´              `----------´  client API  `--------------´
      |
      |                   ,----------.
      `------------------ | m- files |
      Octave interpreter  `----------´

1. Public m-files in the +vibes package folder
   • The user calls the functions from this namespace, e. g., vibes.beginDrawing
   • The function files contain documentation in TexInfo format, e. g., use help vibes.beginDrawing to read it
   • Checks for the correct number or function arguments
   • Unit tests, which are executed as part of the Travis build, or by the user, e. g., test +vibes/beginDrawing
   • Handling of interval data types from the Octave-Forge interval package or from the INTLAB toolbox, e. g., use vibes.drawBox (infsup ("[-1, 1]"), infsup ("[-1, 1]")) to draw a square box with x,y ∈ [-1, 1]
   • The public m-files call the internal __vibes__ function
2. Private oct-file function __vibes__
   • An oct-file is highly efficient, because it is a dynamically loadable object, which communicates with Octave directly
   • Input argument checking and error handling
   • Conversion from Octave data types into C++ data types
   • The internal functions in the oct-file call the bundled C++ client API
3. Bundled VIBes client API for C++
   • Conversion from C++ data types into JSON
   • Communication with the VIBes viewer application

Above components are combined in standard Octave package format, such that they can be installed with the pkg function inside Octave, which automatically handles compilation of the oct-file and adds the package functions to the path.

Although the VIBes client API for Octave will not run in MATLAB, compatibility with the VIBes client API for MATLAB is intended. It shall be possible that MATLAB applications, which use VIBes, can also run in Octave.

Release to Octave-Forge

The Octave client-api is also released at http://octave.sourceforge.net/vibes/.

1. Push the release version to the clone repository at https://sourceforge.net/p/octave/vibes/
2. Also push a release tag release-X.X.X
3. Create the tarballs (Octave package and html) with make -C client-api/Octave release
4. Upload tarballs and md5 to the Package release tracker
5. Once it's accepted, an Octave-Forge admin will upload it and make an announcement on the mailing list.