imatlab/imatlab — 132 Stars

Topics

Language breakdown

Python 89.0%

MATLAB 11.0%

▸ Files click to expand

README

A Jupyter kernel for MATLAB ===========================

Note: This package is no longer actively maintained. Consider using the official MATLAB integration for Jupyter_ instead.

.. _MATLAB integration for Jupyter: https:/www.mathworks.com/products/reference-architectures/jupyter.html

.. contents:: :local:

This kernel requires Jupyter_ with Python 3.5+, and the MATLAB engine for Python_ R2016b+, which needs to be installed first. (We intentionally do not declare a dependency on the matlabengine_ PyPI package to maintain back-compatibility with older versions of MATLAB, for which the engine needs to be manually installed.) Note that additionally, Python versions not supported by the engine are likewise not supported by the kernel.

.. _Jupyter: http://jupyter.readthedocs.org/en/latest/install.html .. _MATLAB engine for Python: https://www.mathworks.com/help/matlab/matlab-engine-for-python.html .. _matlabengine: https://pypi.org/project/matlabengine/

Installation

As usual, install using pip:

.. code-block:: sh

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

Then, register the kernelspec with

.. code:: sh

$ python -mimatlab install

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


Use 

.. code:: sh
# 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 on any 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 addition to 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 display static images, or use Plotly_ to generate interactive JavaScript figures.
.. _Plotly: https://plot.ly/

The exporter is set by calling the imatlabexportfig function, which is automatically added to the MATLAB path when the kernel is running. The following settings are possible:


.. code:: matlab
imatlabexportfig('')  % Native windows.    imatlabexportfig('fig2plotly')  % Plotly figures.    imatlabexportfig('print-png')  % Static png figures.    imatlabexportfig('print-svg')  % Static svg figures.    imatlabexportfig('print-jpeg')  % Static jpeg figures.

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

Plotly exporter <pre><code class="lang-"></code></pre><pre><code class="lang-"></code></pre><pre><code class="lang-">Plotly inline graphics in the notebook depend on plotly.py_ (>=1.13) and the Plotly MATLAB API_ (>=2.2.7), which can be installed as follows:


.. _plotly.py: https://pypi.org/project/plotly/ .. _Plotly MATLAB API: https://plot.ly/matlab

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

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


Recursively add the resulting extracted folders to the MATLAB search path

using addpath(genpath(<Plotly MATLAB API path>));

.  Either put such a
   call in your

startup.m, or then call savepath;

 to save the path.
In MATLAB, copy the required JavaScript files and initialize the
   credentials:
.. code:: matlab
getplotlyoffline(&#39;https://cdn.plot.ly/plotly-latest.min.js&#39;);       try, signin; catch, saveplotlycredentials(&#39;&#39;, &#39;&#39;); end;
(If your version of MATLAB uses an old OpenSSL, you may need to use HTTP    instead of HTTPS.)

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


.. _plotly/MATLAB-Online: https://github.com/plotly/MATLAB-Online .. _zip file: https://github.com/plotly/MATLAB-api/archive/master.zip

Static exporters</code></pre><pre><code class="lang-"></code></pre><pre><code class="lang-"></code></pre>

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

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

Custom exporters <pre><code class="lang-"></code></pre><pre><code class="lang-"></code></pre>``

For further customization, you may override the imatlabexportfig 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; this function should return a cell array of filenames with .html, .png, or .jpg/.jpeg extension. The corresponding files, which should have been created 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 kernel will attempt to connect to the shared engine with that name. If it is set to 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 be changed to match the kernel's working directory.

IMATLAB_CONNECT needs to be set outside of MATLAB (as it is checked before the connection to the engine is made). Other environment variables can be set either 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 one second interval on Linux and OSX, but together after a one second wait on Windows. PRs improving Windows support are welcome.

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


MATLAB debugger

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


Differences with the Calysto MATLAB Kernel

History is read from and written to MATLAB's own History.xml, and thus

  shared 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-only
  setup), history will not be reloaded into later sessions.  (A PR for loading

history.m

 instead would be welcome; it would need to properly parse
  multiline 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 for
  this purpose (

cd, edit