Calysto / octave_kernel

An Octave kernel for Jupyter Prerequisites Jupyter Notebook and GNU Octave. Installation To install using pip: To install using conda: We require the or executable to run the kernel. Add that executable's directory to the environment variable or create the environment variable to point to the executable itself. Note that on Octave 5+ on Windows, the executable is in . We automatically install a Jupyter kernelspec when installing the python package. This location can be found using . If the default location is not desired, remove the directory for the kernel, and install using . See for available options. Usage To use the kernel, run one of: This kernel is based on MetaKernel, which means it features a standard set of magics (such as ). For a full list of magics, run in a cell. A sample notebook is available online. Configuration The kernel can be configured by adding an file to the config path. The class offers , , , and as configurable traits. The available plot settings are: 'format', 'backend', 'width', 'height', 'resolution', and 'plot_dir'. The path to the Octave kernel JSON file can also be specified by creating an environment variable. The command line options to Octave can also be specified with an environment variable. The cli options be appended to the default options of . Note that the init file is explicitly called after the kernel has set to prevent a lockup when the pager is invoked in . The inline toolkit is the used to generate plots for the inline backend. It will default to whatever backend defaults to. The different backend can be used for inline plotting either by using this configuration or by using the plot magic and putting the backend name after , e.g. . Supported Platforms The supports running on Linux, MacOS, or Windows. On Linux, it supports Octave installed using , , or . There is no additional configuration required to use or . Managing the Octave Executable The kernel resolves the Octave executable in this order: • The trait set in • The environment variable • on • on • (if Flatpak is installed) If none of the above resolves to a valid Octave installation, the kernel will fail to start with an error. **Using a custom executable path** Set the environment variable before launching Jupyter: Or configure it persistently in : **Windows** On Windows with Octave 5+, the executable lives under . Either add that directory to or point directly at : **Flatpak and Snap** Flatpak and Snap installations are detected automatically - no additional configuration is needed. When a Snap installation is detected, the kernel uses a Snap-writable temp directory ( ) for figures. **Validating the executable** The kernel validates the configured executable at startup by running . If validation fails, the kernel reports which executable was tried and exits with a clear error message. To diagnose the issue manually: Troubleshooting Debugging the Kernel To see detailed Jupyter protocol messages and kernel log output, launch an interactive console session with debug logging: is not installed by default and must be installed separately. This is useful for diagnosing communication issues between Jupyter and the kernel. Kernel Times Out While Starting If the kernel does not start, run the following command from a terminal: 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: If the kernel is still not listed, verify that the following point to the same version of python: Qt Backend Availability In some cases, the graphics toolkit is only available when running with a display enabled. On a remote system without a display, you can use to provide a virtual framebuffer. For example: Or in the config file: JupyterHub with Qt Support To enable Octave's Qt graphics toolkit in a JupyterHub environment (or any headless server), you need a virtual display. Install the required system packages: Start before launching JupyterHub (or in a server startup script): Then configure the kernel to use the Qt backend: For Binder-based deployments, place a script in the directory to launch and export before the server starts, and list the required packages in . Blank Plot Specify a different format using the magic or using a configuration setting. On some systems, the default produces a black plot. On other systems produces a black plot. Local Installation To install from a git checkout run: