Use Eqiora source cells in a Python notebook

Eqiora includes an optional IPython extension for writing Eqiora source in a notebook cell. Install Eqiora 0.1.3 or later using Get started. Ordinary Python scripts keep using eqiora.compile.

Select your Python environment

Use a Python kernel from the environment containing Eqiora. For a local JupyterLab environment, install the notebook tools into that same uv project:

bash

uv add --dev jupyterlab==4.5.11 ipykernel
uv run jupyter lab

In a Python cell, load the extension explicitly:

python

%load_ext eqiora.jupyter
import eqiora

Open the mixed-language example

Download the example files into eqiora-source beside your uv project environment, then generate the example and open it:

bash

uv run python eqiora-source/editor/jupyter/example.py decay.ipynb
uv run jupyter lab decay.ipynb

The generator reads the maintained examples/decay.eqi into an Eqiora source cell. The surrounding Python cells load the extension and inspect the compiled Model; the notebook starts without saved outputs. Choose Kernel → Restart Kernel and Run All Cells to run the complete example in a fresh kernel. The last cell prints the Model digest. This small example compiles the equations; continue with Run and inspect to configure and run a numerical method.

Calibrate from measured data

For a complete solve-and-fit workflow, open the measured-force calibration notebook. It contains the CSV input, full model source, solver settings, typed residuals, mass updates and independent answer checks. Install the development checkout into its Python kernel; the released 0.1.3 wheel predates its data and retained Parameter-product APIs. The notebook runs ordinary Python cells and does not need the IPython source-cell extension. Hosted Colab execution is not yet verified.

Compile a source cell

Create another code cell with this content:

eqiora

%%eqiora model
// A minimal implicit ODE: x decays at the rate supplied by the user.
model decay() {
  // `x` is dimensionless and starts at 1. `rate` has inverse-time units.
  state x: 1;
  initial { x = 1; }
  parameter rate: 1 / s = 1;

  // Eqiora writes the evolution law as a residual equal to zero.
  relation flow {
    derivative(x) + rate * x = 0;
  }
}

After successful execution, model is the ordinary compiled eqiora.Model in the shared Python namespace. Continue with the configuration and execution steps from Run and inspect, using this model in place of that guide’s eqiora.compile(...) call. Editing the cell has no effect on a compiled Model until you execute the cell again.

Compilation errors keep their usual diagnostic codes and source locations, with line and column numbers counted from the %%eqiora header as line 1. If a re-run fails, model keeps the last successfully compiled value.

Supply ordinary compiler inputs

The magic accepts these optional arguments:

text

%%eqiora model --entry SelectedModel --bindings inputs --geometry geometry

SelectedModel is a declaration name. inputs and geometry are names of existing Python variables containing the same bindings and Geometry accepted by eqiora.compile. Supply only the options your source needs. Variable names are single Python identifiers; the extension does not evaluate Python expressions in the header or interpolate the Eqiora body.

Editor support in JupyterLab and Notebook

Eqiora 0.1.3 includes a prebuilt extension for JupyterLab 4.5.11 and Notebook 7.5.6. A code cell that starts with %%eqiora is highlighted with the same grammar as .eqi files, both while you type and after the notebook is reopened. Remove the header and the cell becomes an ordinary Python cell again.

After %load_ext eqiora.jupyter, press Tab at the end of a name for Eqiora completions, and hover over a name to see its declaration, type, and documentation. Both work on incomplete source and never execute the cell or change its Python variable. They see only the current cell: Python variables, other cells, and imported packages are not visible as Eqiora declarations. Completion is not offered inside an existing word, because IPython only replaces text before the cursor, and Shift-Tab inspection is not supported. Python cells keep their normal completion and inspection.

Hover requests go to the notebook’s kernel when it is idle. Cells larger than 256 KiB are not sent, the displayed text is limited to 4096 Unicode code points, and a request gives up after three seconds. Responses that arrive after an edit, a kernel restart, a disconnection, or closing the editor are discarded.

Completion was tested with IPython 9.17.0, and the notebook frontends with IPython 9.17.1 and ipykernel 7.3.0.

Install Eqiora into the environment that runs the Jupyter server as well as the Python kernel if those are separate. Restart the server after installing or updating the extension; uv run jupyter labextension list should list @eqiora/jupyter. The frontend does not need a Node.js build during installation.

All of this was tested on Linux x86-64 with the versions above. VS Code notebooks and Colab do not load this extension.

If %load_ext reports that eqiora.jupyter is absent, check the kernel’s eqiora.__file__ and package version. Upgrade an older installation with uv add eqiora==0.1.3, then restart the kernel. Loading Eqiora in a normal Python process does not load IPython. %unload_ext eqiora.jupyter removes the magic, completion matcher and hover target, leaving existing compiled Models available.