Rebrand numbl-first: this runs numbl (which uses MATLAB syntax)
Lead with numbl as the language/engine and treat MATLAB syntax as
clarifying information rather than the headline, across the README, code
comments, kernelspec (display_name 'numbl (MATLAB syntax)', language
'numbl', language_info.name 'numbl'), package metadata, and demo notebooks.
Functional highlighting identifiers (codemirror_mode 'octave',
pygments_lexer 'matlab') are unchanged, so .m syntax highlighting still
works.
7 changed files+113−143
README.mdmodified+15−14View file
@@ -1,17 +1,17 @@
11 # jupyterlite-numbl-kernel
22
3-A MATLAB-syntax kernel for [JupyterLite](https://jupyterlite.readthedocs.io/) —
4-notebooks that run **entirely in the browser**, with no server, no kernel
5-process, and nothing for the reader to install.
3+Run [**numbl**](https://github.com/flatironinstitute/numbl) in
4+[JupyterLite](https://jupyterlite.readthedocs.io/) notebooks — **entirely in
5+the browser**, with no server, no kernel process, and nothing for the reader
6+to install.
67
7-The language engine is [numbl](https://github.com/flatironinstitute/numbl), an
8-open-source MATLAB-syntax implementation in TypeScript. Each kernel runs a
8+numbl is an open-source numerical-computing engine, written in TypeScript,
9+that uses MATLAB syntax — so `.m` code runs unchanged. This kernel runs a
910 numbl session in a Web Worker in the page: variables persist across cells,
10-console output streams into the running cell, MATLAB plotting commands render
11-as figures in cell outputs (including interactive 3-D), the `mip` package
12-manager can install MATLAB-syntax packages from GitHub, and `.m` files next
13-to the notebook are part of the workspace (named functions, called from
14-cells) — all client-side.
11+console output streams into the running cell, plots render as figures in cell
12+outputs (including interactive 3-D), the `mip` package manager can install
13+numbl packages from GitHub, and `.m` files next to the notebook are part of
14+the workspace (named functions, called from cells) — all client-side.
1515
1616 **Demo site:**
1717 <https://concept-collection.github.io/jupyterlite-numbl-kernel/> (deployed
@@ -19,10 +19,11 @@ from this repo via GitHub Pages — see `.github/workflows/deploy.yml`)
1919
2020 ## Why
2121
22-Existing MATLAB/Octave Jupyter kernels require the real product installed
23-behind a server. This kernel is a proof of concept that a MATLAB-syntax
24-notebook can be a static web page: hostable on GitHub Pages, shareable as a
25-link, and executable by anyone with a browser.
22+This kernel is a proof of concept that a numbl notebook can be a static web
23+page: hostable on GitHub Pages, shareable as a link, and executable by anyone
24+with a browser. Because numbl uses MATLAB syntax and needs no MATLAB/Octave
25+install (or any server process), the same `.m` code that would otherwise
26+require a licensed product behind a server just runs in the tab.
2627
2728 ## How it works
2829
demo/content/01-intro.ipynbmodified+6−21View file
@@ -4,18 +4,7 @@
44 "cell_type": "markdown",
55 "id": "intro-title",
66 "metadata": {},
7- "source": [
8- "# MATLAB syntax, entirely in your browser\n",
9- "\n",
10- "This notebook runs on the **numbl kernel for JupyterLite**. Every cell executes\n",
11- "in a Web Worker in *your* browser tab — there is no server and no kernel\n",
12- "process behind this page, and nothing to install.\n",
13- "\n",
14- "The engine is [numbl](https://github.com/flatironinstitute/numbl), an\n",
15- "open-source MATLAB-syntax language implementation in TypeScript.\n",
16- "\n",
17- "Run the cells below with **Shift+Enter**."
18- ]
7+ "source": "# numbl, entirely in your browser\n\nThis notebook runs on the **numbl kernel for JupyterLite**. Every cell executes\nin a Web Worker in *your* browser tab — there is no server and no kernel\nprocess behind this page, and nothing to install.\n\n[numbl](https://github.com/flatironinstitute/numbl) is an open-source\nnumerical-computing engine written in TypeScript. It uses MATLAB syntax, so\n`.m` code runs unchanged.\n\nRun the cells below with **Shift+Enter**."
198 },
209 {
2110 "cell_type": "code",
@@ -46,11 +35,7 @@
4635 "id": "intro-indexing",
4736 "metadata": {},
4837 "outputs": [],
49- "source": [
50- "% MATLAB indexing: rows, and logical masks\n",
51- "A(2, :)\n",
52- "A(A > 3)'"
53- ]
38+ "source": "% Indexing: rows, and logical masks\nA(2, :)\nA(A > 3)'"
5439 },
5540 {
5641 "cell_type": "code",
@@ -81,7 +66,7 @@
8166 {
8267 "cell_type": "markdown",
8368 "id": "1e814d6c",
84- "source": "## Named functions live in `.m` files\n\nnumbl's cells work like the MATLAB console: you can't define a *named*\nfunction directly in a cell. Instead, put it in a `.m` file next to the\nnotebook — this kernel syncs `.m` files from the file browser into the\nsession before every cell runs, so functions defined there are callable\nimmediately, and edits take effect the next time you run a cell.\n\nThis notebook ships with [statsutils.m](./statsutils.m) — open it, and try\nediting it (e.g. add a `median` field) while the cell below is still there.",
69+ "source": "## Named functions live in `.m` files\n\nnumbl's cells work like a REPL: you can't define a *named* function directly\nin a cell. Instead, put it in a `.m` file next to the notebook — this kernel\nsyncs `.m` files from the file browser into the session before every cell\nruns, so functions defined there are callable immediately, and edits take\neffect the next time you run a cell.\n\nThis notebook ships with [statsutils.m](./statsutils.m) — open it, and try\nediting it (e.g. add a `median` field) while the cell below is still there.",
8570 "metadata": {}
8671 },
8772 {
@@ -104,15 +89,15 @@
10489 ],
10590 "metadata": {
10691 "kernelspec": {
107- "display_name": "MATLAB (numbl)",
108- "language": "matlab",
92+ "display_name": "numbl (MATLAB syntax)",
93+ "language": "numbl",
10994 "name": "numbl"
11095 },
11196 "language_info": {
11297 "codemirror_mode": "octave",
11398 "file_extension": ".m",
11499 "mimetype": "text/x-octave",
115- "name": "matlab",
100+ "name": "numbl",
116101 "pygments_lexer": "matlab"
117102 }
118103 },
demo/content/02-plotting.ipynbmodified+76−85View file
@@ -1,87 +1,78 @@
11 {
2- "cells": [
3- {
4- "cell_type": "markdown",
5- "id": "plot-title",
6- "metadata": {},
7- "source": [
8- "# Plotting\n",
9- "\n",
10- "MATLAB plotting commands render through numbl's figure renderer, straight\n",
11- "into the cell output — no display server involved. 3-D figures are\n",
12- "interactive (drag to rotate).\n",
13- "\n",
14- "Figures are per-cell, like inline matplotlib: each cell renders the figures\n",
15- "its own commands produce."
16- ]
17- },
18- {
19- "cell_type": "code",
20- "execution_count": null,
21- "id": "plot-lines",
22- "metadata": {},
23- "outputs": [],
24- "source": [
25- "x = linspace(0, 2*pi, 200);\n",
26- "plot(x, sin(x), 'b-');\n",
27- "hold on;\n",
28- "plot(x, cos(x), 'r--');\n",
29- "hold off;\n",
30- "title('sin and cos');\n",
31- "xlabel('x');\n",
32- "legend('sin', 'cos');"
33- ]
34- },
35- {
36- "cell_type": "code",
37- "execution_count": null,
38- "id": "plot-subplot",
39- "metadata": {},
40- "outputs": [],
41- "source": [
42- "subplot(1, 2, 1); plot(x, sin(x)); title('sin(x)');\n",
43- "subplot(1, 2, 2); plot(x, sin(2*x)); title('sin(2x)');"
44- ]
45- },
46- {
47- "cell_type": "code",
48- "execution_count": null,
49- "id": "plot-imagesc",
50- "metadata": {},
51- "outputs": [],
52- "source": [
53- "Z = peaks(80);\n",
54- "imagesc(Z);\n",
55- "colorbar;\n",
56- "title('peaks');"
57- ]
58- },
59- {
60- "cell_type": "code",
61- "execution_count": null,
62- "id": "plot-surf",
63- "metadata": {},
64- "outputs": [],
65- "source": [
66- "surf(peaks(40));\n",
67- "title('peaks surface — drag to rotate');"
68- ]
69- }
70- ],
71- "metadata": {
72- "kernelspec": {
73- "display_name": "MATLAB (numbl)",
74- "language": "matlab",
75- "name": "numbl"
76- },
77- "language_info": {
78- "codemirror_mode": "octave",
79- "file_extension": ".m",
80- "mimetype": "text/x-octave",
81- "name": "matlab",
82- "pygments_lexer": "matlab"
83- }
2+ "cells": [
3+ {
4+ "cell_type": "markdown",
5+ "id": "plot-title",
6+ "metadata": {},
7+ "source": "# Plotting\n\nnumbl's plotting commands render through its figure renderer, straight\ninto the cell output — no display server involved. 3-D figures are\ninteractive (drag to rotate).\n\nFigures are per-cell, like inline matplotlib: each cell renders the figures\nits own commands produce."
848 },
85- "nbformat": 4,
86- "nbformat_minor": 5
87-}
9+ {
10+ "cell_type": "code",
11+ "execution_count": null,
12+ "id": "plot-lines",
13+ "metadata": {},
14+ "outputs": [],
15+ "source": [
16+ "x = linspace(0, 2*pi, 200);\n",
17+ "plot(x, sin(x), 'b-');\n",
18+ "hold on;\n",
19+ "plot(x, cos(x), 'r--');\n",
20+ "hold off;\n",
21+ "title('sin and cos');\n",
22+ "xlabel('x');\n",
23+ "legend('sin', 'cos');"
24+ ]
25+ },
26+ {
27+ "cell_type": "code",
28+ "execution_count": null,
29+ "id": "plot-subplot",
30+ "metadata": {},
31+ "outputs": [],
32+ "source": [
33+ "subplot(1, 2, 1); plot(x, sin(x)); title('sin(x)');\n",
34+ "subplot(1, 2, 2); plot(x, sin(2*x)); title('sin(2x)');"
35+ ]
36+ },
37+ {
38+ "cell_type": "code",
39+ "execution_count": null,
40+ "id": "plot-imagesc",
41+ "metadata": {},
42+ "outputs": [],
43+ "source": [
44+ "Z = peaks(80);\n",
45+ "imagesc(Z);\n",
46+ "colorbar;\n",
47+ "title('peaks');"
48+ ]
49+ },
50+ {
51+ "cell_type": "code",
52+ "execution_count": null,
53+ "id": "plot-surf",
54+ "metadata": {},
55+ "outputs": [],
56+ "source": [
57+ "surf(peaks(40));\n",
58+ "title('peaks surface — drag to rotate');"
59+ ]
60+ }
61+ ],
62+ "metadata": {
63+ "kernelspec": {
64+ "display_name": "numbl (MATLAB syntax)",
65+ "language": "numbl",
66+ "name": "numbl"
67+ },
68+ "language_info": {
69+ "codemirror_mode": "octave",
70+ "file_extension": ".m",
71+ "mimetype": "text/x-octave",
72+ "name": "numbl",
73+ "pygments_lexer": "matlab"
74+ }
75+ },
76+ "nbformat": 4,
77+ "nbformat_minor": 5
78+}
demo/content/03-packages.ipynbmodified+4−13View file
@@ -4,16 +4,7 @@
44 "cell_type": "markdown",
55 "id": "pkg-title",
66 "metadata": {},
7- "source": [
8- "# Installing packages — still no server\n",
9- "\n",
10- "numbl ships with `mip`, a package manager for MATLAB-syntax libraries.\n",
11- "Packages are fetched from GitHub releases and cached in your browser's\n",
12- "IndexedDB, so the download happens once.\n",
13- "\n",
14- "The first cell you run in a session also bootstraps the engine, so expect a\n",
15- "short delay (progress is printed)."
16- ]
7+ "source": "# Installing packages — still no server\n\nnumbl ships with `mip`, a package manager for numbl packages. Packages are\nfetched from GitHub releases and cached in your browser's IndexedDB, so the\ndownload happens once.\n\nThe first cell you run in a session also bootstraps the engine, so expect a\nshort delay (progress is printed)."
178 },
189 {
1910 "cell_type": "code",
@@ -50,15 +41,15 @@
5041 ],
5142 "metadata": {
5243 "kernelspec": {
53- "display_name": "MATLAB (numbl)",
54- "language": "matlab",
44+ "display_name": "numbl (MATLAB syntax)",
45+ "language": "numbl",
5546 "name": "numbl"
5647 },
5748 "language_info": {
5849 "codemirror_mode": "octave",
5950 "file_extension": ".m",
6051 "mimetype": "text/x-octave",
61- "name": "matlab",
52+ "name": "numbl",
6253 "pygments_lexer": "matlab"
6354 }
6455 },
package.jsonmodified+3−3View file
@@ -1,15 +1,15 @@
11 {
22 "name": "jupyterlite-numbl-kernel",
33 "version": "0.1.0",
4- "description": "MATLAB-syntax (numbl) kernel for JupyterLite — notebooks run entirely in the browser",
4+ "description": "Run numbl (MATLAB-syntax numerical computing) in JupyterLite notebooks, entirely in the browser",
55 "keywords": [
66 "jupyter",
77 "jupyterlab",
88 "jupyterlab-extension",
99 "jupyterlite",
1010 "jupyterlite-kernel",
11- "matlab",
12- "numbl"
11+ "numbl",
12+ "matlab"
1313 ],
1414 "homepage": "https://github.com/concept-collection/jupyterlite-numbl-kernel",
1515 "bugs": {
src/index.tsmodified+3−3View file
@@ -13,7 +13,7 @@ const NUMBL_LOGO =
1313 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8IS0tIEJhY2tncm91bmQgLS0+CiAgPHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiBmaWxsPSIjNjQ3NDhiIiByeD0iNCIvPgoKICA8IS0tIE1hdHJpeCBicmFja2V0cyBhbmQgZG90cyAod2hpdGUgb24gYmx1ZSkgLS0+CiAgPGcgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBmaWxsPSJub25lIiBzdHJva2UtbGluZWNhcD0icm91bmQiPgogICAgPCEtLSBMZWZ0IGJyYWNrZXQgLS0+CiAgICA8cGF0aCBkPSJNIDggOSBMIDYgOSBMIDYgMjMgTCA4IDIzIi8+CiAgICA8IS0tIFJpZ2h0IGJyYWNrZXQgLS0+CiAgICA8cGF0aCBkPSJNIDI0IDkgTCAyNiA5IEwgMjYgMjMgTCAyNCAyMyIvPgogIDwvZz4KCiAgPCEtLSBNYXRyaXggZG90cyAtLT4KICA8ZyBmaWxsPSJ3aGl0ZSI+CiAgICA8Y2lyY2xlIGN4PSIxMiIgY3k9IjEzIiByPSIxLjUiLz4KICAgIDxjaXJjbGUgY3g9IjE2IiBjeT0iMTMiIHI9IjEuNSIvPgogICAgPGNpcmNsZSBjeD0iMjAiIGN5PSIxMyIgcj0iMS41Ii8+CgogICAgPGNpcmNsZSBjeD0iMTIiIGN5PSIxOSIgcj0iMS41Ii8+CiAgICA8Y2lyY2xlIGN4PSIxNiIgY3k9IjE5IiByPSIxLjUiLz4KICAgIDxjaXJjbGUgY3g9IjIwIiBjeT0iMTkiIHI9IjEuNSIvPgogIDwvZz4KPC9zdmc+Cg==';
1414
1515 /**
16- * A plugin to register the numbl (MATLAB-syntax) kernel.
16+ * A plugin to register the numbl kernel.
1717 */
1818 const kernel: JupyterFrontEndPlugin<void> = {
1919 id: 'jupyterlite-numbl-kernel:kernel',
@@ -23,8 +23,8 @@ const kernel: JupyterFrontEndPlugin<void> = {
2323 kernelspecs.register({
2424 spec: {
2525 name: 'numbl',
26- display_name: 'MATLAB (numbl)',
27- language: 'matlab',
26+ display_name: 'numbl (MATLAB syntax)',
27+ language: 'numbl',
2828 argv: [],
2929 resources: {
3030 'logo-32x32': NUMBL_LOGO,
src/kernel.tsmodified+6−4View file
@@ -10,8 +10,8 @@ import type { NumblSession } from 'numbl/browser';
1010 export const FIGURE_MIME = 'application/vnd.numbl.figure+json';
1111
1212 /**
13- * A JupyterLite kernel that executes MATLAB-syntax code with numbl,
14- * entirely in the browser.
13+ * A JupyterLite kernel that runs numbl — a MATLAB-syntax numerical
14+ * computing engine — entirely in the browser.
1515 *
1616 * Each kernel owns one numbl session (a Web Worker managed by numbl):
1717 * variables persist across cells, console output streams to the running
@@ -44,10 +44,12 @@ export class NumblKernel extends BaseKernel {
4444 implementation: 'numbl',
4545 implementation_version: '0.1.0',
4646 language_info: {
47+ // numbl uses MATLAB syntax; the octave/matlab modes drive
48+ // highlighting in the notebook and on nbconvert export.
4749 codemirror_mode: 'octave',
4850 file_extension: '.m',
4951 mimetype: 'text/x-octave',
50- name: 'matlab',
52+ name: 'numbl',
5153 nbconvert_exporter: 'script',
5254 pygments_lexer: 'matlab',
5355 version: 'numbl'
@@ -142,7 +144,7 @@ export class NumblKernel extends BaseKernel {
142144
143145 /**
144146 * Handle an `is_complete_request` message: treat every submission as a
145- * complete MATLAB statement (the console runs on Enter).
147+ * complete numbl statement (the console runs on Enter).
146148 */
147149 async isCompleteRequest(
148150 content: KernelMessage.IIsCompleteRequestMsg['content']