Skip to main content

A Jupyter kernel for Octave.

Project description

An Octave kernel for Jupyter
============================

Prerequisites
-------------
`Jupyter Notebook <http://jupyter.readthedocs.org/en/latest/install.html>`_ and GNU Octave_.

It is recommended to also install ``gnuplot`` for Octave to enable inline plotting.

Installation
------------
To install using pip::

pip install octave_kernel

Add ``--user`` to install in the user-level environment instead of the system environment.

To install using conda::

conda config --add channels conda-forge
conda install octave_kernel
conda install texinfo # For the inline documentation (shift-tab) to appear.

We require the ``octave-cli`` executable to run the kernel.
Add that executable's directory to the ``PATH`` environment variable or use the
``OCTAVE_EXECUTABLE`` to point to the executable itself.
Note that on Octave 5 on Windows, the executable is in ``"Octave-5.x.x.x\mingw64\bin"``.

We automatically install a Jupyter kernelspec when installing the
python package. This location can be found using ``jupyter kernelspec list``.
If the default location is not desired, remove the directory for the
``octave`` kernel, and install using ``python -m octave_kernel install``. See
``python -m octave_kernel install --help`` for available options.

Usage
-----
To use the kernel, run one of:

.. code:: shell

jupyter notebook # or ``jupyter lab``, if available
# In the notebook interface, select Octave from the 'New' menu
jupyter qtconsole --kernel octave
jupyter console --kernel octave

This kernel is based on `MetaKernel <http://pypi.python.org/pypi/metakernel>`_,
which means it features a standard set of magics (such as ``%%html``). For a full list of magics,
run ``%lsmagic`` in a cell.

A sample notebook is available online_.


Configuration
-------------
The kernel can be configured by adding an ``octave_kernel_config.py`` file to the
``jupyter`` config path. The ``OctaveKernel`` class offers ``plot_settings``, ``inline_toolkit``,
``kernel_json``, and ``cli_options`` as configurable traits. The available plot settings are:
'format', 'backend', 'width', 'height', and 'resolution'.

.. code:: bash
cat ~/.jupyter/octave_kernel_config.py
# use Qt as the default backend for plots
c.OctaveKernel.plot_settings = dict(backend='qt')


The path to the Octave kernel JSON file can also be specified by creating an
``OCTAVE_KERNEL_JSON`` environment variable.

The command line options to Octave can also be specified with an
``OCTAVE_CLI_OPTIONS`` environment variable. The cli options be appended to the
default opions of ``--interactive --quiet --no-init-file``. Note that the
init file is explicitly called after the kernel has set ``more off`` to prevent
a lockup when the pager is invoked in ``~/.octaverc``.

The inline toolkit is the ``graphics_toolkit`` used to generate plots for the inline
backend. It defaults to ``gnuplot``.


Troubleshooting
---------------

Kernel Times Out While Starting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the kernel does not start, run the following command from a terminal:

.. code:: shell

python -m octave_kernel.check

This can help diagnose problems with setting up integration with Octave. If in doubt,
create an issue with the output of that command.


Kernel is Not Listed
~~~~~~~~~~~~~~~~~~~~
If the kernel is not listed as an available kernel, first try the following command:

.. code:: shell

python -m octave_kernel install --user

If the kernel is still not listed, verify that the following point to the same
version of python:

.. code:: shell

which python # use "where" if using cmd.exe
which jupyter


Gnuplot Error
~~~~~~~~~~~~~
An error that starts with ``gnuplot> set terminal aqua enhanced title`` can be fixed by
adding ``setenv("GNUTERM","qt");`` to ``~/.octaverc`` on MacOS or by installing
``gunplot-x11`` and using ``setenv("GNUTERM", "X11")``.

Blank Plot
~~~~~~~~~~
Specify a different format using the `%plot -f <backend>` magic or using a configuration setting.
On some systems, the default 'png' produces a black plot. On other systems 'svg' produces a
black plot.


.. _Octave: https://www.gnu.org/software/octave/download.html
.. _online: http://nbviewer.ipython.org/github/Calysto/octave_kernel/blob/master/octave_kernel.ipynb


Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

octave_kernel-0.30.0.tar.gz (24.7 kB view details)

Uploaded Source

Built Distribution

octave_kernel-0.30.0-py3-none-any.whl (33.3 kB view details)

Uploaded Python 3

File details

Details for the file octave_kernel-0.30.0.tar.gz.

File metadata

  • Download URL: octave_kernel-0.30.0.tar.gz
  • Upload date:
  • Size: 24.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for octave_kernel-0.30.0.tar.gz
Algorithm Hash digest
SHA256 4798889d82bfde548dd6684dffcfd56f9c5d87aaa5c10c53bcd3d534dc2f2fd1
MD5 090792a7783dd907c9d8ba86de2fabde
BLAKE2b-256 52cca6359ee33606ea09d331aa25c75bd978391dfd1a6293a286fb86bbd4356a

See more details on using hashes here.

Provenance

File details

Details for the file octave_kernel-0.30.0-py3-none-any.whl.

File metadata

  • Download URL: octave_kernel-0.30.0-py3-none-any.whl
  • Upload date:
  • Size: 33.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for octave_kernel-0.30.0-py3-none-any.whl
Algorithm Hash digest
SHA256 71f0a10bbc7a4b08ea354a77be0f0c50488bea5163a36babac2de127bcefbd9c
MD5 8be48352116c8eac4f8c2619d6b28e29
BLAKE2b-256 e30e3c181f93b84a053b29a8769c1d7eba2e0a1fe9b1bc0ff1bac5d4e7722a87

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page