API Reference¶

Manages an Octave session.

Uses MAT files to pass data between Octave and Numpy. The function must either exist as an m-file in this directory or on Octave’s path. The first command will take about 0.5s for Octave to load up. The subsequent commands will be much faster.

You may provide a logger object for logging events, or the oct2py.get_log() default will be used. When calling commands, logger.info() will be used to stream output, unless a stream_handler is provided.

Start Octave and set up the session.

logger¶

The logging instance used by the session.

exit()[source]¶

Quits this octave session and cleans up.

push(name, var, timeout=None, verbose=True)[source]¶

Put a variable or variables into the Octave session.

Parameters:	name : str or list Name of the variable(s). var : object or list The value(s) to pass. timeout : float Time to wait for response from Octave (per line). **kwargs: Deprecated kwargs, ignored.

Notes

Integer type arguments will be converted to floating point unless convert_to_float=False.

Examples

>>> from oct2py import octave
>>> y = [1, 2]
>>> octave.push('y', y)
>>> octave.pull('y')
array([[ 1.,  2.]])
>>> octave.push(['x', 'y'], ['spam', [1, 2, 3, 4]])
>>> octave.pull(['x', 'y'])  
[u'spam', array([[1, 2, 3, 4]])]

pull(var, timeout=None, verbose=True)[source]¶

Retrieve a value or values from the Octave session.

Parameters:	var : str or list Name of the variable(s) to retrieve. timeout : float, optional. Time to wait for response from Octave (per line). **kwargs: Deprecated kwargs, ignored.
Returns:	out : object Object returned by Octave.
Raises:	Oct2PyError If the variable does not exist in the Octave session.

Examples

>>> from oct2py import octave
>>> y = [1, 2]
>>> octave.push('y', y)
>>> octave.pull('y')
array([[ 1.,  2.]])
>>> octave.push(['x', 'y'], ['spam', [1, 2, 3, 4]])
>>> octave.pull(['x', 'y'])  
[u'spam', array([[1, 2, 3, 4]])]

get_pointer(name, timeout=None)[source]¶

Get a pointer to a named object in the Octave workspace.

Parameters:	name: str The name of the object in the Octave workspace. timemout: float, optional. Time to wait for response from Octave (per line).
Returns:	A variable, object, user class, or function pointer as appropriate.
Raises:	Oct2PyError If the variable does not exist in the Octave session or is of unknown type.

Notes

Pointers can be passed to feval or dynamic functions as function arguments. A pointer passed as a nested value will be passed by value instead.

Examples

>>> from oct2py import octave
>>> octave.eval('foo = [1, 2];')
>>> ptr = octave.get_pointer('foo')
>>> ptr.value
array([[ 1.,  2.]])
>>> ptr.address
'foo'
>>> # Can be passed as an argument
>>> octave.disp(ptr)  
1  2

>>> from oct2py import octave
>>> sin = octave.get_pointer('sin')  # equivalent to `octave.sin`
>>> sin.address
'@sin'
>>> x = octave.quad(sin, 0, octave.pi())
>>> x
2.0

extract_figures(plot_dir, remove=False)[source]¶

Extract the figures in the directory to IPython display objects.

Parameters:	plot_dir: str The plot dir where the figures were created. remove: bool, optional. Whether to remove the plot directory after saving.

feval(func_path, *func_args, **kwargs)[source]¶

Run a function in Octave and return the result.

Parameters:

func_path: str Name of function to run or a path to an m-file. func_args: object, optional Args to send to the function. nout: int, optional Desired number of return arguments, defaults to 1. store_as: str, optional If given, saves the result to the given Octave variable name instead of returning it. verbose : bool, optional Log Octave output at INFO level. If False, log at DEBUG level. stream_handler: callable, optional A function that is called for each line of output from the evaluation. timeout: float, optional The timeout in seconds for the call. plot_dir: str, optional If specificed, save the session’s plot figures to the plot directory instead of displaying the plot window. plot_name : str, optional Saved plots will start with plot_name and end with “_%%.xxx’ where %% is the plot number and xxx is the plot_format. plot_format: str, optional The format in which to save the plot. plot_width: int, optional The plot with in pixels. plot_height: int, optional The plot height in pixels.

Returns:

The Python value(s) returned by the Octave function call.

Notes

The function arguments passed follow Octave calling convention, not Python. That is, all values must be passed as a comma separated list, not using x=foo assignment.

Examples

>>> from oct2py import octave
>>> cell = octave.feval('cell', 10, 10, 10)
>>> cell.shape
(10, 10, 10)

>>> from oct2py import octave
>>> x = octave.feval('linspace', 0, octave.pi() / 2)
>>> x.shape
(1, 100)

>>> from oct2py import octave
>>> x = octave.feval('svd', octave.hilb(3))
>>> x
array([[ 1.40831893],
       [ 0.12232707],
       [ 0.00268734]])
>>> # specify three return values
>>> (u, v, d) = octave.feval('svd', octave.hilb(3), nout=3)
>>> u.shape
(3, 3)

eval(cmds, verbose=True, timeout=None, stream_handler=None, temp_dir=None, plot_dir=None, plot_name='plot', plot_format='svg', plot_width=None, plot_height=None, plot_res=None, nout=0, **kwargs)[source]¶

Evaluate an Octave command or commands.

Parameters:	cmds : str or list Commands(s) to pass to Octave. verbose : bool, optional Log Octave output at INFO level. If False, log at DEBUG level. stream_handler: callable, optional A function that is called for each line of output from the evaluation. timeout : float, optional Time to wait for response from Octave (per line). If not given, the instance timeout is used. nout : int, optional. The desired number of returned values, defaults to 0. If nout is 0, the ans will be returned as the return value. temp_dir: str, optional If specified, the session’s MAT files will be created in the directory, otherwise a the instance temp_dir is used. a shared memory (tmpfs) path. plot_dir: str, optional If specificed, save the session’s plot figures to the plot directory instead of displaying the plot window. plot_name : str, optional Saved plots will start with plot_name and end with “_%%.xxx’ where %% is the plot number and xxx is the plot_format. plot_format: str, optional The format in which to save the plot (PNG by default). plot_width: int, optional The plot with in pixels. plot_height: int, optional The plot height in pixels. plot_res: int, optional The plot resolution in pixels per inch. **kwargs Deprectated kwargs.
Returns:	out : object Octave “ans” variable, or None.
Raises:	Oct2PyError If the command(s) fail.

Notes

The deprecated log kwarg will temporarily set the logger level to WARN. Using the logger settings directly is preferred. The deprecated return_both kwarg will still work, but the preferred method is to use the stream_handler. If stream_handler is given, the return_both kwarg will be honored but will give an empty string as the reponse.

Examples

>>> from oct2py import octave
>>> octave.eval('disp("hello")') 
hello
>>> x = octave.eval('round(quad(@sin, 0, pi/2));')
>>> x
1.0

>>> a = octave.eval('disp("hello");1;')  
hello
>>> a = octave.eval('disp("hello");1;', verbose=False)
>>> a
1.0

>>> from oct2py import octave
>>> lines = []
>>> octave.eval('for i = 1:3; disp(i);end',                         stream_handler=lines.append)
>>> lines  
[' 1', ' 2', ' 3']

restart()[source]¶

Restart an Octave session in a clean state

Octave style struct, enhanced.

Notes

Supports dictionary and attribute style access. Can be pickled, and supports code completion in a REPL.

Examples

>>> from pprint import pprint
>>> from oct2py import Struct
>>> a = Struct()
>>> a.b = 'spam'  # a["b"] == 'spam'
>>> a.c["d"] = 'eggs'  # a.c.d == 'eggs'
>>> pprint(a)
{'b': 'spam', 'c': {'d': 'eggs'}}

A Python representation of an Octave cell array.

Notes

This class is not meant to be directly created by the user. It is created automatically for cell array values received from Octave. The last axis is squeezed if it is of size 1 to simplify element access.

Examples

>>> from oct2py import octave
>>> # generate the struct array
>>> octave.eval("x = cell(2,2); x(:) = 1.0;")
>>> x = octave.pull('x')
>>> x
Cell([[1.0, 1.0],
       [1.0, 1.0]])
>>> x[0]
Cell([1.0, 1.0])
>>> x[0].tolist()
[1.0, 1.0]

Create a cell array from a value and optional Octave session.

A Python representation of an Octave structure array.

Notes

Accessing a record returns a Cell containing the values. This class is not meant to be directly created by the user. It is created automatically for structure array values received from Octave. The last axis is squeezed if it is of size 1 to simplify element access.

Examples

>>> from oct2py import octave
>>> # generate the struct array
>>> octave.eval('x = struct("y", {1, 2}, "z", {3, 4});')
>>> x = octave.pull('x')
>>> x.y  # attribute access -> oct2py Cell
Cell([[1.0, 2.0]])
>>> x['z']  # item access -> oct2py Cell
Cell([[3.0, 4.0]])
>>> x[0, 0]  # index access -> numpy record
(1.0, 3.0)
>>> x[0, 1].z
4.0

Create a struct array from a value and optional Octave session.

Called when we can’t open Octave or Octave throws an error