A Jupyter kernel for MATLAB

This kernel requires Jupyter with Python 3.5+, and the MATLAB engine forPython R2016b+ (this release provides a much better completion API), whichneeds to be installed first. Note that additionally, Python versions notsupported by the engine are likewise not supported by the kernel.

Installation

As usual, install using pip:

$ pip install imatlab  # from PyPI
$ pip install git+https://github.com/imatlab/imatlab  # from Github

Then, register the kernelspec with

$ python -mimatlab install

In the absence of administrator rights, the --user flag should be added toall of these commands.

Use

# Notebook (in the notebook interface, select Matlab from the 'New' menu):
$ jupyter notebook
# or QtConsole:
$ jupyter qtconsole --kernel imatlab
# or terminal:
$ jupyter console --kernel imatlab

(Note that imatlab intentionally does not declare a dependency onany Jupyter client, as it can be used with any one of them individually.In practice, this means that at least one of jupyter-notebook,jupyter-qtconsole, or jupyter-console need to be installed in additionto imatlab.)

Inline graphics

MATLAB figures can be displayed in native MATLAB windows (the default), or(when using the notebook) as inline images. The kernel can natively displaystatic images, or use Plotly to generate interactiveJavaScript figures.

The exporter is set by calling the imatlab_export_fig function, which isautomatically added to the MATLAB path when the kernel is running. Thefollowing settings are possible:

imatlab_export_fig('')  % Native windows.
imatlab_export_fig('fig2plotly')  % Plotly figures.
imatlab_export_fig('print-png')  % Static png figures.
imatlab_export_fig('print-svg')  % Static svg figures.
imatlab_export_fig('print-jpeg')  % Static jpeg figures.

This call must be issued before the first figure is shown. Note that thenon-native exporters will call set(0, 'defaultfigurevisible', 'off') toprevent the window from being briefly displayed, whereas using native windowsturns the default figure visibility back 'on'.

Plotly exporter

Plotly inline graphics in the notebook depend on plotly.py (>=1.13) and thePlotly MATLAB API (>=2.2.7), which can be installed as follows:

1. Run pip install plotly or pip install --user plotly.

2. Clone plotly/MATLAB-Online or download it as a zip file.

3. Recursively add the resulting extracted folders to the MATLAB search pathusing addpath(genpath(<Plotly MATLAB API path>));. Either put such acall in your startup.m, or then call savepath; to save the path.

4. In MATLAB, copy the required JavaScript files and initialize thecredentials:

   getplotlyoffline('https://cdn.plot.ly/plotly-latest.min.js');
   try, signin; catch, saveplotlycredentials('', ''); end;

   (If your version of MATLAB uses an old OpenSSL, you may need to use HTTPinstead of HTTPS.)

At the beginning of each notebook, you may then callimatlab_export_fig('fig2plotly') to use automatically Plotly inlinegraphics (no further calls to the Plotly API are required; in particular,ignore the output from getplotlyoffline).

Static exporters

The static exporters (png, svg, and jpeg) do not required additionaldependencies.

The default size of exported figures, as well as whether to display figuresbefore exporting them, should be set using standard figure properties (set(0,'defaultpaperposition', [left, bottom, width, height]);, etc.).

Custom exporters

For further customization, you may override the imatlab_export_fig function(the default version is provided by imatlab and added to the MATLAB path).This function is called with no arguments after each notebook cell is executed,while the current directory is temporarily switched to a temporary folder; thisfunction should return a cell array of filenames with .html, .png, or.jpg/.jpeg extension. The corresponding files, which should have beencreated by the function, will be loaded into the notebook.

Environment variables

IMATLAB_CONNECT

If this environment variable is set to a valid MATLAB identifier, the kernelwill attempt to connect to the shared engine with that name. If it is setto another non-empty value, it will connect to any existing shared engine.

IMATLAB_CD

If this environment variable is set, the engine's working directory will bechanged to match the kernel's working directory.

IMATLAB_CONNECT needs to be set outside of MATLAB (as it is checked beforethe connection to the engine is made). Other environment variables can be seteither outside of MATLAB (before starting the kernel) or from within MATLAB(using setenv).

Asynchronous output

A construct such as 1, pause(1), 2 will output 1 and 2 with a onesecond interval on Linux and OSX, but together after a one second wait onWindows. PRs improving Windows support are welcome.

Asynchronous output using timer objects seem to be completely unsupportedby the MATLAB engine for Python.

MATLAB debugger

The MATLAB debugger is cleared (dbclear all) before each execution, asinteractive input is not supported by the engine API.

Differences with the Calysto MATLAB Kernel

• The completion system is much more robust, by relying on the new APIavailable in MATLAB 2016b.
• History is read from and written to MATLAB's own History.xml, and thusshared with standard MATLAB sessions. Note that if the file does not exist(e.g. if the don't save history file option is set, or in a console-onlysetup), history will not be reloaded into later sessions. (A PR for loadinghistory.m instead would be welcome; it would need to properly parsemultiline inputs in that file.)
• Synchronous output is supported on Linux and OSX (see above).
• There is no magics systems, as MATLAB already provides many functions forthis purpose (cd, edit, etc.).
• Inline graphics can be based on plotly, and thus interactive.

Tests

Run tests with python -munittest or pytest after installing the kernel andjupyter_kernel_test.