You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- When you execute MATLAB code in a notebook for the first time, enter your MATLAB license information in the dialog box that appears. See [Licensing](https://github.com/mathworks/matlab-proxy/blob/main/MATLAB-Licensing-Info.md) for details. The MATLAB session can take a few minutes to start.
152
-
- 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.
153
-
- With MATLAB R2022b and later, you can define a local function at the end of the cell where you want to call it:
151
+
### Notes
152
+
153
+
-**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.
154
+
-**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.
155
+
-**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:
For technical details about how the MATLAB kernel works, see [MATLAB Kernel for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/src/jupyter_matlab_kernel/README.md).
157
+
158
+
-**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).
159
+
160
+
-**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).
156
161
157
162
## Open MATLAB in a Browser
158
163
@@ -189,8 +194,6 @@ This opens an untitled `.m` file where you can write MATLAB code with syntax hig
189
194
* Currently, this package allows you to edit MATLAB `.m` files but not to execute them.
190
195
* To open a new MATLAB `.m` file, you can also use the JupyterLab command palette. Press `CTRL+SHIFT+C`, then type `New MATLAB File` and press `Enter`.
191
196
192
-
193
-
194
197
## Limitations
195
198
196
199
* This package has limitations. For example, it does not support certain MATLAB commands. For details, see [Limitations](https://github.com/mathworks/jupyter-matlab-proxy/blob/main/limitations.md).
A connection error occurred while connecting to MATLAB.
26
-
27
-
Args:
28
-
message (string): Error message to be displayed
29
-
"""
30
-
31
-
def__init__(self, message=None):
32
-
ifmessageisNone:
33
-
message='Error connecting to MATLAB. Check the status of MATLAB by clicking the "Open MATLAB" button. Retry after ensuring MATLAB is running successfully'
You can use magic commands with the MATLAB kernel. You can use the predefined magic commands in this folder, and you can implement your own by following the steps below.
4
+
5
+
## Get Started
6
+
7
+
Magic commands for the MATLAB kernel are prefixed with two percentage symbols `%%` without whitespaces. For example, to list available magic commands, run `%%lsmagic`
8
+
9
+
Note that magic commands will only work at the beginning of cells, and will not work with MATLAB variables.
10
+
11
+
The magic commands `help` and `file` accept additional parameters. For example, to display information about a magic command, run `%%help` followed by the name of the magic as an argument: `%%help time`
12
+
13
+
This table lists the predefined magic commands you can use:
|help|Display information about provided magic command. | Name of magic command.||`%%help file`|
20
+
|time|Display time taken to execute a cell.|||`%%time`|
21
+
|file|Save contents of cell as a file in the notebook folder. You can use this command to define and save new functions. For details, see the section below on how to [Create New Functions Using the %%file Magic Command](#create-new-functions-using-the-the-file-magic-command)|Name of saved file|The file magic command will save the contents of the cell, but not execute them in MATLAB|`%%file myfile.m`|
22
+
23
+
24
+
To request a new magic command, [create an issue](https://github.com/mathworks/jupyter-matlab-proxy/issues/new/choose).
25
+
26
+
## Create Your Own Magic Commands
27
+
28
+
To implement your own magic commands, follow these steps. You can use the predefined magic commands as examples.
29
+
30
+
1. In the `magics` folder, create a Python file with the name of your new magic command, for example `<new_magic_name>.py`.
31
+
2. Create a child class that inherits from the `MATLABMagic` class located in `jupyter_matlab_kernel/magics/base/matlab_magic.py` and modify these function members:
32
+
1. info_about_magic
33
+
2. skip_matlab_execution
34
+
3. before_cell_execute
35
+
4. after_cell_execute
36
+
5. do_complete
37
+
For details about these fields, see the descriptions in the `MATLABMagic` class.
38
+
3. Add tests for your magic command in the `tests/unit/jupyter_matlab_kernel/magics` folder.
39
+
40
+
## Create New Functions Using the the %%file Magic Command
41
+
42
+
In a notebook cell you can define MATLAB functions that are scoped to that cell. To define a function scoped to all the cells in a notebook, you can use the `%%file` magic command. Define a new function and save it as a MATLAB `.m` file, using the name of the function as the file name. For example, to create a function called `myAdditionFunction(x, y)`, follow these steps:
43
+
44
+
1. In a notebook cell, use the `%%file` command and define the function.
45
+
46
+
```
47
+
%%file myAdditionFunction.m
48
+
49
+
function addition = myAdditionFunction(x, y)
50
+
addition = x + y;
51
+
end
52
+
```
53
+
54
+
2. Run the cell to create a file called `myAdditionFunction.m` in the same folder as your notebook.
55
+
56
+
57
+
3. You can then use this function in other cells of the notebook.
58
+
59
+
```
60
+
addition = myAdditionFunction(3, 4);
61
+
disp(addition)
62
+
```
63
+
64
+
Note: to use your function in MATLAB, remember to set your MATLAB search path to the folder containing your notebook. For more information on setting the search path, see [Change Folders on Search Path](https://www.mathworks.com/help/matlab/matlab_env/add-remove-or-reorder-folders-on-the-search-path.html).
message="An uncaught error occurred during magic execution."
14
+
super().__init__(message)
15
+
16
+
17
+
classMagicExecutionEngineError(Exception):
18
+
"""Custom exception for error in Magic Execution Engine.
19
+
20
+
Args:
21
+
message (string): Error message to be displayed
22
+
"""
23
+
24
+
def__init__(self, message=None):
25
+
ifmessageisNone:
26
+
message="An uncaught error occurred in the Magic Execution Engine."
27
+
super().__init__(message)
28
+
29
+
30
+
classMATLABConnectionError(Exception):
31
+
"""
32
+
A connection error occurred while connecting to MATLAB.
33
+
34
+
Args:
35
+
message (string): Error message to be displayed
36
+
"""
37
+
38
+
def__init__(self, message=None):
39
+
ifmessageisNone:
40
+
message='Error connecting to MATLAB. Check the status of MATLAB by clicking the "Open MATLAB" button. Retry after ensuring MATLAB is running successfully'
0 commit comments