Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/imatlab/imatlab

A Jupyter kernel for MATLAB.
https://github.com/imatlab/imatlab

jupyter matlab

Last synced: 26 days ago
JSON representation

A Jupyter kernel for MATLAB.

Awesome Lists containing this project

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



-----



|Python35| |MATLAB2016b| |PyPI|



.. |Python35| image:: https://img.shields.io/badge/python-3.5%2B-blue.svg

.. |MATLAB2016b| image:: https://img.shields.io/badge/MATLAB-2016b%2B-blue.svg

.. |PyPI|

   image:: https://img.shields.io/pypi/v/imatlab.svg

   :target: https://pypi.python.org/pypi/imatlab



.. 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 ``imatlab_export_fig`` function, which is

automatically added to the MATLAB path when the kernel is running.  The

following settings are possible:



.. code:: matlab



   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 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

```````````````



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



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 path

   using ``addpath(genpath());``.  Either put such a

   call in your ``startup.m``, or then call ``savepath;`` to save the path.

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

   credentials:



   .. code:: matlab



      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 HTTP

   instead of HTTPS.)



At the beginning of each notebook, you may then call

``imatlab_export_fig('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

````````````````



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

````````````````



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; 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``, etc.).

- Inline graphics can be based on ``plotly``, and thus interactive.



Tests

-----



Run tests with ``python -munittest`` or pytest_ after installing the kernel and

jupyter_kernel_test_.



.. _pytest: https://pytest.org

.. _jupyter_kernel_test: https://pypi.python.org/pypi/jupyter_kernel_test