Choosing a kernel: standard Jupyter, ipykernel, or MathJet's kernel
MathJet can run .ipynb notebooks against three different kernel modes. They form a spectrum — from full Jupyter compatibility with no MathJet-specific features, through a middle ground that gives you variable inspection and interactive plots while keeping your existing kernel environment, to MathJet’s own kernel where variables live in MathJet’s process and every GUI surface can read and write them directly.
This page explains the three modes, what each one gives you, and when to choose which.
The three modes
Section titled “The three modes”1. Standard Jupyter kernel
Section titled “1. Standard Jupyter kernel”MathJet connects to any Jupyter or IPython kernel via the standard Jupyter messaging protocol (ZeroMQ, shell/iopub/stdin sockets). This is plain message-passing for code execution: MathJet sends cell contents to the kernel, receives outputs (text, HTML, images), and renders them in the notebook view.
What you get: Byte-identical behavior with vanilla Jupyter or JupyterLab. Your kernel environment, pip packages, conda environments, and remote Jupyter servers all work exactly as they do today. If you have a notebook that works in Jupyter, it works in MathJet on a standard kernel with zero changes.
What you don’t get: Variables exist only inside the kernel process. MathJet’s GUI has no window into them — the Environment Pane stays empty, the Overview Pane has nothing to show. Matplotlib figures render as static PNG images. DataFrame outputs are read-only HTML tables. There’s no way for MathJet to intercept, inspect, or edit anything the kernel holds.
When to use it: When you need exact behavioral parity with Jupyter — for example, when running a notebook against a remote kernel server, or when your notebook depends on a specific kernel environment that MathJet’s kernel can’t replicate.
2. ipykernel with comm channel
Section titled “2. ipykernel with comm channel”Same Jupyter messaging protocol as mode 1, but with an additional bidirectional comm channel that lets MathJet register custom message handlers with the kernel. The comm channel is part of the Jupyter messaging spec — it’s the mechanism that ipywidgets, custom Jupyter extensions, and other frontends use to exchange structured data with the kernel outside the normal execute/result flow.
MathJet uses the comm channel to:
- Query the kernel’s namespace after each cell execution and populate the Environment Pane with variable names, types, sizes, and (for small objects) preview data.
- Intercept matplotlib figure objects at render time and present them as native MathJet charts instead of rasterizing to PNG. The interception happens via a custom matplotlib backend that MathJet’s comm handler installs in the kernel process.
- Relay DataFrame edits from the GUI back to the kernel. When you edit a cell in a DataFrame’s variable cell block, MathJet sends a comm message to the kernel with the index, column, and new value; the kernel applies the change to the in-memory DataFrame.
What you get: Variable inspection in the Environment Pane. Interactive matplotlib charts (zoom, pan, split, selection sync). Editable DataFrame cell blocks in the notebook output area — though the edit path is indirect (GUI → comm message → kernel → kernel applies change), so there’s a round-trip latency and the edit surface is narrower than MathJet’s kernel mode.
What you don’t get: Cross-language access. The variables live in the kernel’s Python process, not in MathJet’s shared data frame. Jet and R can’t see them; Excel formulas in a worksheet can’t reference them; you can’t send a variable to a worksheet and get a live-linked cell block. The Environment Pane shows the variables, but they’re views across a process boundary, not shared-memory references.
When to use it: When you need a specific kernel environment (a particular Python version, a conda environment with specific packages, a GPU-enabled kernel) but still want the variable inspection and interactive plot features. This is the middle ground: most of the interactive experience, all of the kernel flexibility.
3. MathJet kernel
Section titled “3. MathJet kernel”MathJet runs Python in its own process. There’s no separate kernel process and no messaging protocol between frontend and kernel — the Python interpreter is embedded in MathJet the same way Jet and R are.
Variables live in MathJet’s shared data frame directly. The same shared data frame that Tutorial 2 demonstrates for polyglot formulas and mixed-language scripts is the one the notebook’s variables land in. When a cell creates a pandas DataFrame, that DataFrame is immediately visible to Jet, R, Excel formulas, worksheets, charts, the Environment Pane, and every other MathJet surface — not because MathJet queries the kernel for it, but because it’s already in the same memory space.
What you get: Everything in mode 2, plus:
- Cross-language access. Switch the Command Editor to R and type
summary(df)— R sees the notebook’s DataFrame directly. - Live-linked worksheets and charts. Send a variable to a worksheet; edits in the worksheet write back to the variable; downstream notebook cells that reference the variable pick up the change on re-execution.
- Direct DataFrame editing. Edits in a variable cell block write to the DataFrame in-process — no comm-message round-trip, no serialization. The edit is a direct memory write, the same way editing a cell in a Jet variable cell block works.
- Full GUI surface integration. Data Repair, data nudging, the Workspace Manager’s multi-pane sync, Create Variable from Cells — every MathJet feature that operates on variables in the shared data frame works with notebook-produced variables.
What you don’t get: The kernel is MathJet’s embedded Python, not your system’s standalone Python. If your notebook depends on a specific Python version, a conda environment, or packages that aren’t installed in MathJet’s Python, the notebook may not run on MathJet’s kernel. (MathJet’s Python uses the same pip ecosystem, so most packages install normally — but environment-specific constraints may apply.)
When to use it: When you want the full MathJet experience and your notebook’s package requirements are satisfied by MathJet’s Python environment. This is the recommended default for new work.
Feature comparison
Section titled “Feature comparison”| Feature | Standard kernel | ipykernel (with comm) | MathJet kernel |
|---|---|---|---|
| Variable inspection in Environment Pane | No | Yes | Yes |
| matplotlib → interactive MathJet chart | No | Yes | Yes |
| Editable DataFrame cell block | No | Partial (edit-back via comm) | Yes (direct) |
| HTML table output → native worksheet | Yes | Yes | Yes |
| Cross-language access (Jet, R) | No | No | Yes |
| Live link to other GUI surfaces (worksheet ↔ notebook) | No | No | Yes |
.ipynb format preserved | Yes | Yes | Yes |
pip packages from your environment | Yes | Yes | Yes (MathJet’s Python) |
| Remote Jupyter server | Yes | Yes (if server supports comm) | No |
Custom conda environment | Yes | Yes | No |
Switching between modes
Section titled “Switching between modes”The kernel mode is chosen per notebook, per session. Open Kernel → Change Kernel in the notebook editor’s toolbar. The picker is organized in three sections:
- In-process kernels — kernels already running in this session (including MathJet’s own kernel).
- New kernels — available kernels from the chosen interpreter for the notebook’s language. MathJet distinguishes ipykernel entries (comm-channel support, mode 2) from standard Jupyter kernel entries (plain messaging, mode 1). This section also includes Start Remote Kernel for connecting to a Jupyter server.
- Connect to existing kernel — attach to a kernel process already running outside MathJet, by connection file or URL.
Pick MathJet kernel for mode 3, an ipykernel entry for mode 2, or a standard Jupyter kernel for mode 1.
Switching kernels restarts execution. Variables from the previous kernel are lost — the new kernel starts fresh. The notebook file itself is unchanged; the kernel choice is a session property, not a file property.
You can also set a default kernel preference in Preferences → Notebooks → Default kernel, so new notebooks open with your preferred mode without the picker.
The architectural reason for three modes
Section titled “The architectural reason for three modes”The three modes exist because of a genuine architectural trade-off, not because MathJet’s kernel is unfinished.
A standard Jupyter kernel runs in its own process. That process boundary is what gives you environment isolation (any Python, any packages, any machine) but is also what prevents MathJet’s GUI from reaching the variables directly. The comm channel (mode 2) punches a hole in that boundary — enough for inspection and plot interception, not enough for shared-memory semantics.
MathJet’s kernel (mode 3) eliminates the boundary entirely. The Python interpreter runs in MathJet’s process, shares MathJet’s memory, and participates in MathJet’s shared data frame. That’s why cross-language access and live-linked worksheets work — they depend on the variables being in the same address space, not on a messaging protocol that ferries data between processes.
The trade-off is real: mode 3 gives you the most capable experience but ties you to MathJet’s Python environment. Mode 2 keeps your environment but gives up the shared-memory features. Mode 1 gives up everything MathJet-specific in exchange for exact Jupyter compatibility. The right choice depends on what your workflow needs.