NAME

Inline::Octave - Inline octave code into your perl

SYNOPSIS

   use Inline Octave => DATA;
   
   $f = jnk1(3);
   print "jnk1=",$f->disp(),"\n";

   $c= new Inline::Octave::Matrix([ [1.5,2,3],[4.5,1,-1] ]);
   
   ($b, $t)= jnk2( $c, [4,4],[5,6] );
   print "t=",$t->as_list(),"\n";
   use Data::Dumper; print Dumper( $b->as_matrix() );
   
   print oct_sum( [1,2,3] )->disp();

   oct_plot( [0..4], [3,2,1,2,3] );
   sleep(2);
   
   
   __DATA__
   
   __Octave__
   function x=jnk1(u); x=u+1; endfunction
   
   function [b,t]=jnk2(x,a,b);
      b=x+1+a'*b;
      t=6;
   endfunction
   
   ## Inline::Octave::oct_sum (nargout=1)  => sum
   ## Inline::Octave::oct_plot (nargout=0)  => plot

DESCRIPTION

Inline::Octave gives you the power of the octave programming language from within your Perl programs.

You need to install the Inline module from CPAN. This provides the infrastructure to support all the Inline::* modules.

Then install Octave.pm in an Inline directory in any path in your @INC.

The easiest is to create a ./Inline directory in your working directory, and put Octave.pm in that. after that the example code should run.

Note, there is currently no proper Makefile.PL install facility for Inline::Octave - this reflects it's maturity.

It should work with stock octave - but I'd like to get feedback on this. Basically, I create an octave process with controlled stdin and stdout. Commands send by stdin. Data is send by stdin and read with fread(stdin, [dimx dimy], "double"), and read similarly.

Inline::Octave::Matrix variables in perl are tied to the octave variable. When a destructor is called, it sends a "clear varname" command to octave.

I initially tried to bind the C++ and liboctave to perl, but it started to get really hard - so I took this route.

Why would I use Inline::Octave

If you can't figure out a reason, don't!

I use it to grind through long logfiles (using perl), and then calculate mathematical results (using octave).

Using Inline::Octave

The most basic form for using Inline is:

   use Inline Octave => "octave source code";
             

The source code can be specified using any of the following syntaxes:

   use Inline Octave => 'DATA';
   ...perl...                                                                    
   __DATA__
   __Octave__
   ...octave...

or,

   use Inline Octave => <<'ENDOCTAVE';
   ...octave...
   ENDOCTAVE
   ...perl...

or,

   use Inline Octave => q{
   ...octave...
   };
   ...perl...

Defining Functions

Inline::Octave lets you:

1) Talk to octave functions using the syntax

   ## Inline::Octave::oct_plot (nargout=0)  => plot

Here oct_plot in perl is bound to plot in octave. It is necessary to specify the nargouts required because we can't get this information from perl. (although it's promised in perl6)

If you need to use various nargouts for a function, then bind different functions to it:

   ## Inline::Octave::eig1 (nargout=1)  => eig
   ## Inline::Octave::eig2 (nargout=2)  => eig

2) Write new octave functions,

      function s=add(a,b);
         s=a+b;
      endfunction

will create a new function add in perl bound to this new function in octave.

Calling Functions

A function is called using

   (list of Inline::Octave::Matrix) =
      function_name (list of Inline::Octave::Matrix)

Parameters which are not Inline::Octave::Matrix variables will be cast (if possible).

Values returned will need to be converted into perl values if they need to be used within the perl code. This can be accomplished using:

1. $oct_var->disp()

Returns a string of the disp output from octave

2. $oct_var->as_list()

Returns a perl list, corresponding to the ColumnVector for octave "oct_var(:)"

3. $oct_var->as_matrix()

Returns a perl list of list, of the form

   $var= [ [1,2,3],[4,5,6],[7,8,9] ];

4. $oct_var->as_scalar()

Returns a perl scalar if $oct_var is a 1x1 matrix, dies with an error otherwise

Using Inline::Octave::Matrix

Inline::Octave::Matrix is the matrix class that "ties" (but not using the Perl "tie" mechanism)

Values can be created explicitly, using the syntax:

   $var= new Inline::Octave::Matrix([ [1.5,2,3],[4.5,1,-1] ]);

or values will be automatically created by calling octave functions.

PERFORMANCE

Performance should be almost as good as octave alone. The only slowdown is passing large variables across the pipe between perl and octave - but this should be much faster than any actual computations.

By using the strengths of both languages, it should be possible to run faster than in each. (ie using octave for matrix operations, and running loops and text stuff in perl)

AUTHOR

Andy Adler andy@analyti.ca

COPYRIGHT

© MMI, Andy Adler

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

TODO List

   1. Add import for functions
   2. control matrix size inputs
   3. add destructor for Octave::Matrix
       - done
   4. control waiting in the interpret loop
       - seems ok, except sysread reads small buffers
   5. support for complex variables

cpanm Inline::Octave

perl -MCPAN -e shell
install Inline::Octave