A Juyter kernel for MATLAB.
A Jupyter kernel for MATLAB
This kernel requires Jupyter with Python 3.5+, and the MATLAB engine for Python R2016b+ (this release provides a much better completion API), which needs to be installed first. Note that additionally, Python versions not supported by the engine are likewise not supported by the kernel.
Install with python -mpip install imatlab (from PyPI) or python -mpip install git+https://github.com/imatlab/imatlab (from Github); then run python -mimatlab install to register the kernel spec. In the absence of administrator rights, the --user flag should be added to any of these commands.
To use it, run one of:
$ jupyter notebook # In the notebook interface, select Matlab from the 'New' menu $ jupyter qtconsole --kernel imatlab $ jupyter console --kernel imatlab
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:
imatlab_export_fig('') % Native windows. imatlab_export_fig('fig2plotly') % Plotly figures. imatlab_export_fig('print-png') % Static png 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'.
To use Plotly inline graphics in the notebook, the Plotly MATLAB API (>=2.2.7) must be installed, as follows:
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.
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).
The static exporters (png 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.).
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.
- 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.
- 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).
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.
The MATLAB debugger is cleared (dbclear all) before each execution, as interactive input is not supported by the engine API.
- The completion system is much more robust, by relying on the new API available in MATLAB 2016b.
- 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.