Skip to content

Commit

Permalink
Updates to README files.
Browse files Browse the repository at this point in the history
  • Loading branch information
@zainh-mw @prabhakk-mw
zainh-mw authored and prabhakk-mw committed Sep 23, 2024
1 parent 41bbb13 commit 6ff852c
Show file tree
Hide file tree
Showing 3 changed files with 37 additions and 126 deletions.
18 changes: 14 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ cd jupyter-matlab-proxy
python -m pip install .
```

### Integration with JupyterHub
### Using JupyterHub

To use MATLAB with JupyterHub, install the `jupyter-matlab-proxy` Python package in the Jupyter environment launched by your JupyterHub platform. For example, if your JupyterHub platform launches Docker containers, install this package in the Docker image used to launch those containers, using the instructions for [Using MATLAB Integration _for Jupyter_ in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab).

Expand Down Expand Up @@ -151,13 +151,23 @@ This opens a Jupyter notebook that supports MATLAB.
### Notes

- **Licensing:** When you execute MATLAB code in a notebook for the first time, enter your MATLAB license information in the dialog box that appears. For details, see [Licensing](https://github.com/mathworks/matlab-proxy/blob/main/MATLAB-Licensing-Info.md). The MATLAB session can take a few minutes to start.
- **Multiple notebooks:** Multiple notebooks running on a Jupyter server share the underlying MATLAB process, so executing code in one notebook affects the workspace in others. If you work in several notebooks simultaneously, be aware that they share a workspace.
- **Local functions:** with MATLAB R2022b and later, you can define a local function at the end of the cell where you want to call it:

- **MATLAB Kernel:** The MATLAB kernel supports tab completion and rich outputs:
* Inline static plot images
* LaTeX representation for symbolic expressions
* Tables formatted using HTML instead of ASCII, in MATLAB R2024a and later:
| Before R2024a | After R2024a |
|--|--|
|<p align="center"><img width="450" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/tables_before_r2024a.png"></p> | <p align="center"><img width="400" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/tables_after_r2024a.png"></p> |

For a technical overview of the MATLAB kernel, see [MATLAB Kernel for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/src/jupyter_matlab_kernel/README.md).

- **Multiple notebooks:** Multiple notebooks running on a Jupyter server share the underlying MATLAB process, so executing code in one notebook affects the workspace in others. If you work in several notebooks simultaneously, be aware they share a workspace. For details, see [MATLAB Kernel for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/src/jupyter_matlab_kernel/README.md).
- **Local functions:** With MATLAB R2022b and later, you can define a local function at the end of the cell where you want to call it:
<p><img width="350" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/local_functions.png"></p>

- **Magic Commands:** You can use predefined magic commands in a Jupyter notebook with the MATLAB kernel, and you can also implement your own. To see a list of predefined magic commands, run `%%lsmagic`. For details about using magic commands, see [Magic Commands for MATLAB Kernel](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/src/jupyter_matlab_kernel/magics/README.md).

- **Kernel:** For technical details about the MATLAB kernel, see [MATLAB Kernel for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/src/jupyter_matlab_kernel/README.md).

## Open MATLAB in a Browser

Expand Down
53 changes: 12 additions & 41 deletions src/jupyter_matlab_kernel/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,38 @@
# MATLAB Kernel for Jupyter

This module is a part of the `jupyter-matlab-proxy` package and it provides a Jupyter kernel for the MATLAB language.
This page provides a technical overview of the MATLAB kernel used in the [MATLAB Integration for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy).

## Usage

Upon successful installation of `jupyter-matlab-proxy`, your Jupyter environment should present several options for using MATLAB in Jupyter.

Click on `MATLAB Kernel` to create a Jupyter notebook for MATLAB.
After installing the MATLAB Integration for Jupyter, your Jupyter environment shows different options for using MATLAB in Jupyter. Click `MATLAB Kernel` to start a Jupyter notebook.

|Jupyter Notebook| JupyterLab |
|--|--|
|<p align="center"><img width="200" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/classic-jupyter-kernel.png"></p> | <p align="center"><img width="500" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/jupyterlab_kernel_icon.png"></p> |

## Architecture

|![kernelArchitecture](https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/kernel-architecture.png)|
|-|

**Key takeaways:**

* When a notebook is opened, a new kernel is created for it.

* When the first execution request is made the following occurs:
* A licensing screen is presented if this information has not been provided previously.
* A MATLAB process is launched by Jupyter if one has not been launched previously.

* Every subsequent notebook does **not** ask for licensing information or launch a new MATLAB process.
## Technical Overview

* Every notebook communicates with MATLAB through the Jupyter notebook server.

* A notebook can be thought of as another view into the MATLAB process.
* Any variables or data created through the notebook manifests in the spawned MATLAB process.
* This implies that all notebooks access the same MATLAB workspace, and users must keep this in mind when working with multiple notebooks.
|<p align="center"><img width="600" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/kernel-architecture.png"></p>|
|--|
|The diagram above illustrates that multiple Jupyter notebooks communicate with a shared MATLAB process, through the Jupyter notebook server.|

* If simultaneous execution requests are made from two notebooks, they are processed by MATLAB in a **first-in, first-out basis**.
Start a Jupyter notebook to create a MATLAB kernel. When you run MATLAB code in a notebook for the first time, you see a licensing screen to enter your MATLAB license details. If a MATLAB process is not already running, Jupyter will start one.

* Kernel interrupts can be used to interrupt the execution that is currently being processed by MATLAB.
Multiple notebooks share the same MATLAB workspace. MATLAB processes commands from multiple notebooks in on a first-in, first-out basis.

**Note**: If cells from multiple notebooks are being run at the same time, the execution request that gets interrupted may not be the one from which the interrupt was requested.
You can use kernel interrupts to stop MATLAB from processing a request. Remember that if cells from multiple notebooks are being run at the same time, the execution request you interrupt may not be from the notebook where you initated the interrupt.

## Key Features
* Tab completion
* Execution of MATLAB code
* Rich outputs including:
* Inline static plot images
* LaTeX representation for symbolic expressions
* **For MATLAB R2022b and later:** Local functions can be defined at the end of a cell for use in the same cell
<p><img src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/local_functions.png"></p>
* **For MATLAB R2024a and later:** Tables are formatted using HTML instead of ASCII
| Before R2024a | After R2024a |
|--|--|
|<p align="center"><img width="550" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/tables_before_r2024a.png"></p> | <p align="center"><img width="500" src="https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/tables_after_r2024a.png"></p> |

## Limitations
Please refer to this [README](https://github.com/mathworks/jupyter-matlab-proxy#limitations) file for a listing of the current limitations.
For limitations of the MATLAB kernel, see [Limitations](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/Limitations.md).

## Feedback

We encourage you to try this repository with your environment and provide feedback.
If you encounter a technical issue or have an enhancement request, create an issue [here](https://github.com/mathworks/jupyter-matlab-proxy/issues) or send an email to `[email protected]`
To request an enhancement or technical support, [create a GitHub issue](https://github.com/mathworks/jupyter-matlab-proxy/issues) or send an email to `[email protected]`.

----

Copyright 2023 The MathWorks, Inc.
Copyright 2023-2024 The MathWorks, Inc.

----
92 changes: 11 additions & 81 deletions troubleshooting/troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,35 @@
# Troubleshooting guide for MATLAB Integration _for Jupyter_
We have provided a Python script, troubleshooting.py, which runs basic environment checks to determine if the required dependencies are met or not. This script does not send the information anywhere remotely and just relays information to the terminal window.

This folder contains `troubleshooting.py`, a Python script that checks your environment for the dependencies required to run [MATLAB Integration for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/tree/main). The script prints the results in your terminal.


## Table of Contents
1. [Requirements](#requirements)
2. [Running the script](#running-the-script)
2. [Run Troubleshooting Script](#run-troubleshooting-script)
3. [Enable Logging](#enable-logging)

## Requirements
* Python

## Running the script
One can run the latest version of the troubleshooting script using the following command:

```bash
$ curl https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py | python -
```
- Python

Ensure that the `python` executable used to run this script is from the same environment in which you intend to use the integration.
## Run Troubleshooting Script

Also, if you are on a platform that doesn't support `curl`, please consider downloading the [troubleshooting.py](https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py) and running it as:
Ensure the Python executable you use to run the troubleshooting script is in the same environment where you want to use the integration.

```bash
$ python troubleshooting.py
```
Run the troubleshooting script:

Alternatively, you can manually execute the below commands in the environment where you have installed the package:

* Verify that the MATLAB executable is on the PATH
```bash
$ which matlab
/usr/local/bin/matlab
```

* Check if the Python version is 3.8 or higher
```bash
$ python --version
Python 3.8.3
```

* Ensure that `matlab-proxy-app` and the `jupyter` executables are in the same environment as the Python executable.
For example, if you are using VENV to manage your Python environments:
```bash
$ which python
/home/user/my-project/packages/.venv/bin/python

$ which matlab-proxy-app
/home/user/my-project/packages/.venv/bin/matlab-proxy-app

$ which jupyter
/home/user/my-project/packages/.venv/bin/jupyter
$ curl https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py | python -
```
Notice that `matlab-proxy-app`, `jupyter` and the `python` executable are in the same parent directory, in this case, it is: `/home/user/my-project/packages/.venv/bin`

* Ensure that you are launching `jupyter lab` using the same executable listed above.
If your platform does not support `curl`, download [troubleshooting.py](https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py) and run it:

* Ensure that all three packages are installed in the same Python environment
```bash
# Pipe the output of pip freeze and grep for jupyter, matlab-proxy and jupyter-matlab-proxy.
# All three packages should be highlighted in the output.
# If you don't see any one of them, then either the packages missing in the output have been installed
# in a different Python environment or not installed at all.
$ pip freeze | grep -E "jupyter|matlab-proxy|jupyter-matlab-proxy"
```

* If the integration is not a visible option in the dropdown box inside the Jupyter Notebook:
```bash
#Run the following commands and verify that you are able to see similar output:

$ jupyter serverextension list
config dir: /home/user/anaconda3/etc/jupyter
jupyter_server_proxy enabled
- Validating...
jupyter_server_proxy OK
jupyterlab enabled
- Validating...
jupyterlab 3.5.1 OK

$ jupyter nbextension list
Known nbextensions:
config dir: /home/user/anaconda3/etc/jupyter/nbconfig
notebook section
jupyter-js-widgets/extension enabled
- Validating: OK
tree section
jupyter_server_proxy/tree enabled
- Validating: OK $ pip freeze | grep -E "jupyter|matlab-proxy|jupyter-matlab-proxy"

$ jupyter labextension list
jupyterlab_pygments v0.2.2 enabled OK (python, jupyterlab_pygments)
jupyter_matlab_labextension v0.1.0 enabled OK
@jupyterlab/server-proxy v3.2.2 enabled OK


# IF the server does not show up in the commands above, install:
$ pip install jupyter-contrib-nbextensions
$ python troubleshooting.py
```

## Enable Logging

You can use logs to assist debugging while using MATLAB Integration for Jupyter. Set the environment variable `MWI_JUPYTER_LOG_LEVEL` to one of the following: `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. The default value is `INFO`. For more information on Python log levels, see [Logging Levels](https://docs.python.org/3/library/logging.html#logging-levels).
You can use logs to assist debugging when using MATLAB Integration for Jupyter. Set the environment variable `MWI_JUPYTER_LOG_LEVEL` to one of the following: `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. The default value is `INFO`. For more information on Python log levels, see [Logging Levels (Python)](https://docs.python.org/3/library/logging.html#logging-levels).

To set the environment variable, use the appropriate command for your environment. For example, in Linux, use the following:

Expand Down

0 comments on commit 6ff852c

Please sign in to comment.