Xeus関連の情報(PyData Osaka 2020/8/2用の記事)

• 最近のJupyter Blogから一部記事を抜粋して紹介します。
• Xeus関連の情報がメインです

Xeus is now Jupyter subproject (2020/2/4)

Xeusとは

• Jupyter kernel protocolのC++実装
  • ipykernelの代替として使用可能
• Xeusはカーネルではなくカーネルを作るためのライブラリ
• いくつかのカーネルはXeusを元に作られている
  • 下記はXeusメンテナたちによるもの
  • xeus-cling
    • CERNのCling C++インタプリタベースのカーネル
  • xeus-python
    • pythonインタプリタを埋め込んだpython用カーネル
    • @jupyterlab/debuggerで用いられるJupyter debugger protocolを初めて実装(後述)
    • Debug Adapter Protocolに対応
  • xeus-calc
    • 電卓カーネル、Xeusの使い方を学ぶためのプロジェクト
• Xeusプロジェクトとは関係なく作成されているカーネル
  • JuniperKernel
    • R用カーネル
  • xeus-fift
    • fiftなるTelegramによって作られたTON blockchain contractのためのプログラミング言語向けカーネル
  • SlicerJupyter
    • Kitwareによる"Slicer"プロジェクトのQtイベントループと統合されたPython向けカーネル

XeusがJupyter管轄下へと移行した理由

以下に引用

While Xeus started as a side project for QuantStack engineers,
the project now has several stakeholders who depend on it.
We think that moving the project to an open governance organization may be a better way to reflect this situation.

A visual debugger for Jupyter (2020/3/26)

• 日本語の紹介記事
  • https://www.publickey1.jp/blog/20/jupyterlab.html

概要

• Jupyter向けのvisual debuggerに関する紹介
• debuggerでできることの例
  • ブレークポイントの設定(ノートブックのセルおよびソースファイル)
  • 変数一覧の表示
  • コールスタックの表示
• リンク先のbinderから試しに実行可能

インストール方法

フロントエンドとなるプラグインとバックエンドとなるカーネルが必要

フロントエンド

$ jupyter labextension install @jupyterlab/debugger

このデバッガフロントエンドは将来のリリースにおいてはデフォルトで同梱される予定。

バックエンド

• Jupyter Debug Protocol(次の節で説明)を実装したカーネルが必要
  • このプロトコルを実装したカーネルはいまのところxeus-pythonのみ
• ipykernelにデバッガプロトコルを実装するのはロードマップには存在

$ conda install xeus-python -c conda-forge

• プラットフォームによってはPyPIのwheelsも使えるがまだ実験段階のもの

• condaで試しにinstallして試してみたところxeus-pythonではmatplotlibがうまく扱えない模様

  • https://github.com/jupyter-xeus/xeus-python/issues/224

Jupyter Debug Protocol

ControlおよびIOPub Channelに対する新しいメッセージタイプ

• Jupyter kernelはプロセス間コミュニケーションプロトコル(https://jupyter-client.readthedocs.io/en/stable/messaging.html)に基づき動作
  • Shellチャンネルはコード実行のリクエストなどのrequest/replyを行う
  • IOPubチャンネルはkernelからclientへの片方向のチャンネル(標準出力やエラー出力で使用)
  • ControlチャンネルはShellチャンネルに似ているが別ソケットで実行され、実行キューに溜めないhigh priorityなメッセージを扱う
    • InterruptやShutdownリクエストなど
    • debuggerに送られるコマンドに対してControlチャンネルを使うことに決めた
• protocolに2つのメッセージタイプを追加
  • debug_request/reply
    • breakpointの追加やコードに対するstep into操作などのdebuggerによって実行される特定のアクションのrequest
    • Controlチャンネルに送られる
  • debug_event
    • debugging kernelからフロントエンドに対して片方向に送られるdebug eventメッセージ
    • IOPubチャンネルを通じて送られる

Debug Adapter Protocolの拡張

• Jupyterにおけるデザインのキーとなる原理としてプログラミング言語について不可知であるというものがある
  • Jupyter debug protocolが他のカーネル実装に対しても適用できるものであることは重要である
• 標準的なプロトコルとしてMicrosoftの"Debug Adapter Protocol"(DAP)がある
  • JSONベースのprotocolでありVSCode下で様々な言語のバックエンドとして既に動作
• JupyterでDAPを用いることが自然であるが、Jupyterにおける要件を満たすためには十分ではない
  • ページ再読み込みのサポートが必要
    • Jupyter kernelはデバッガの状態(breakpointや現在どこでstopしているか)を後から接続したclientのために保持しなければならない
    • フロントエンドはその状態をdebug_requestメッセージで要求できる
  • ソースファイルベースではないnotebookのcellとconsoleに対するデバッグのサポートが必要
    • ブレークポイントを追加できるコードをdebuggerに送るためのメッセージが必要
• これらの変更はJEPとして提案されている
  • 文書はこちら

Xeus-python, the first Jupyter Kernel to support debugging

• XeusはC++はJupyter kernelプロトコルのC++実装
  • それ自身がkernelではなくkernel作成を補助するlibrary
  • CやC++ APIを持つ言語に対するカーネルを作成するのに便利
    • Python、Lua、SQLなど
• Xeus-pythonはdebugging protocolを実装する最初の実装として適切
  • プラガブルなconcurrencyモデルを持っているためControlチャンネルを別スレッドで動作させることが可能
  • 上記を繰り返し動作させるために便利なサンドボックスを持つ軽量なコードベースを持つ
    • ipykernelでdebuggingプロトコルを実装することはかなりのリファクタリングを要し早い段階でのconsensus buildingが必要となる
• Xeus-pythonのロードマップ
  • ipykernelに対して失われているmagicを追加
  • PyPI wheelsを改善
• 他のカーネルにおけるdebugging
  • xeusベースのkernelについては大部分の実装が共有可能であるため例えばxeus-clingなどでは早期に使用可能となる

Diving into the debugger front-end architecture

• jupyterlabのdebugger extensionはユーザーが典型的なIDEから予想するようなUIを含む
  • サイドバーに変数エクスプローラ、ブレークポイントのリスト、ソースプレビュー、コールスタックを表示
  • コードの横に直接ブレークポイントを設定できる(cell/console)
  • 現在コードのどの部分で停止しているかを示すヴィジュアルマーカー
• screencastで種々の機能を説明
  • 実行後に削除したセルに対するstep intoはread-only viewとして表示される
  • コンソールおよびファイルに対してもデバッガは有効
  • デバッグはノートブックレベルで実行されるため異なるノートブックに対して同時にデバッグを実行できる
  • 変数一覧はtree形式およびtable形式で閲覧可能

Future developments

• 2020年の予定
  • 変数ビューワでmime type renderingのサポート
  • 条件付きブレークポイントのサポート
  • debugger UXの向上
  • Voilå dashboardのデバッグの有効化

A Jupyter Kernel for SQLite

概要

• SQLite用jupyterカーネルの紹介
  • SQLiteのシンタックスをcode cellで受け付ける
  • magixコマンドでDBのオープンやクローズなどを行う
• Xeusを用いて作成
  • wrapperのSQLiteCppを使用

現在の状況

• 現在進行形で開発中だが下記を備えている
  • SQLiteインタフェースに対する完全な機能
  • 高レベル操作のためのmagic
    • DBの作成、オープン、クローズ、バックアップ
    • テーブルの存在チェック、keyの設定および解除、それらの情報の取得
• テーブル表示
  • jupyter lab/notebookではHTMLで表示
  • コンソールではtabulateライブラリを使って表示

future

• 直感的なデータ表示(plot, graph, chart, mapsなど)の描画
  • Vegaを使えないかを検討中(ブログの画像を参照)
• xeus-SQLiteとSQLiteライブラリのstaticビルドをバンドルしたシングルバイナリの供給

その他

• binderで試しに実行可能(ブログ記事にリンク有)
• インストール方法
  • mamba install xeus-sqlite -c conda-forge
  • conda install xeus-sqlite -c conda-forge
  • mambaはcondaのc++による再実装らしい
    • 並列ダウンロードや高速な依存性解決を備えるとのこと

SlicerJupyter: a 3D Slicer kernel for interactive publications

概要

• 3D Slicer
  • Qtを用いたC++で書かれたデスクトップアプリケーション
    • 医用画像の分析および可視化に使用
  • 3D描画にVisualization Toolkit(VTK)を用い、画像処理にInsight Toolkit(ITK)を用いている
  • pythonインタプリタが埋め込まれている
  • xeus-pythonのインタプリタを統合すればQtベースのデスクトップアプリケーションがnotebookを通じて操作できることを紹介
• githubのSlicerJupyterに実装が存在
  • BlenderやFreeCAD、ParaViewといったpythonが埋め込まれた他のアプリケーションに対しても拡張可能
• xeus-python integrationがJupyterのエコシステムとデスクトップアプリケーションの両方に対して必要不可欠

Powerful Medical Imaging Capabilities Available Through Jupyter

• 3D Slicer(以下Slicer)は内蔵しているpythonインタプリタを通じてすべての機能をpyhonから操作可能
  • pythonインタプリタに対する単純なコンソールは備えているがcellベースのインタラクティブ環境は備えていない
• xeus-pythonを統合することによってSlicerのプロセスをJupyter kernelとして使用可能
• xeus-pythonはitkwidgetsのようなJupyter widgetsへのインタフェースとなるだけではなく、SlicerインタプリタのようなカスタムインタプリタやQtイベントループのようなGUIイベントループとも統合することが可能
  • これによりSlicer内部表現であるMedical Reality Markup Language(MRML)の表現が可能となる
  • ノートブック内でpandasやNumPy配列のようなpythonのエコシステムを通じて完全なmedical imaging APIとデータへとアクセスが可能となる

対話的操作におけるレベル

• JupyterのWidget(sliderやボタンなど)をSlicer操作やデータ変更、処理やパラメータ可視化のために使える

• Widgetを通じた対話的操作は異なるレベルごとに実装されている

• Level1

  • Jupyter Widgetがアプリケーション固有のオブジェクトを自動変換の上で表示
  • 例えばSlicer markup fiducial listはフォーマット済みのテーブルとして表示され、モデルnodeは3Dオブジェクトとして描画される
• Level2
  • Static image widgetがデスクトップアプリケーションが描画したコンテンツを描画
  • これらのwidgetは追加された標準Widgetを用いてデータや描画パラメータが変更されることによって作成される
  • 様々なデータ型や非常に大きなデータセットなどの洗練された描画をJupyterから直接可能とする
• Level3
  • Dynamic viewer Widgetがデスクトップアプリケーションが描画した2D/3D viewをを描画
  • マウス/キーボードのイベントがデスクトップアプリケーションへと送られズームや回転を実現
    • アノテーションの付与、測定、画像分割のような3D対話操作をデスクトップアプリケーション上と同じように行える
    • これはipycanvasとipyeventsパッケージを用いて実現される

• Level4

  • 完全なGUI統合
    • ユーザーはアプリケーションウインドウを標準デスクトップWidget(スライダーやメニューなど)を含めてノートブックセルの中から見ることができる
    • これはSlicer Jupyterの中ではnoVNCとTigerVNCを用いて実現される
    • リモートサーバー上でアプリケーションが実行されているときに便利

• 現在は大部分の実装については安定しているが、まだデザイン面での改善やパフォーマンスの改善の余地がある

  • 自動変換(display hookの複雑な実装による)
  • xeus-pythonのスレッディングモデルはメインスレッドをロックしないように改良する余地がある
  • Level3の統合におけるdynamic viewer widgetはより高いリフレッシュレート実現のためにパフォーマンス最適化の余地がある

History of Slicer and this integration

• QtベースのデスクトップアプリケーションによってXeusカーネルのイベントループが駆動されている？

概要

jupyterlab内でwavファイルが開けなかったのでチュートリアルを参考にMIMEレンダラーを作成しました。 正直wavファイルの場合は上記チュートリアルと全く同じ操作で作成できてしまいました。

プロジェクトの初期化

cookiecutterを使って雛形を生成します。

❯ cookiecutter https://github.com/jupyterlab/mimerender-cookiecutter-ts.git
author_name []: wrist
author_email []: stoicheia1986@gmail.com
extension_name [myextension]: jupyterlab-wav
viewer_name [My Viewer]: JupyterLab wav viewer
mimetype [application/vnd.my_organization.my_type]: audio/wav
mimetype_name [my_type]: wav
file_extension [.my_type]: .wav
Select data_format:
1 - string
2 - json
Choose from 1, 2 (1, 2) [1]: 1

Extensionのビルドとインストール

Extensionの作成にはyarnのバージョンが固定されたjlpmというjupyterlab付属のツールを用いて行います。 依存パッケージをインストールし、Extensionをビルドし、jupyterlabのextensionとしてインストールするためには下記を実行します。

jlpm install
jlpm run build
jupyter labextension install . --no-build

ここで上記をローカル環境で試したところ、jupyterlabのバージョンが1.2.1の場合は現在のJupyterlabとはバージョンの互換性がないというエラーがでてしまいました(既に2.0.0以上を想定している模様です)。

このためjupyterlabを動作させるために使用しているdocker imageであるwrist/jupyterlab-customを更新したのですが、 jupyterlab-vimは2.x系に対応してなかったので代わりに https://github.com/jwkvam/jupyterlab-vim/pull/115 などを参照し、 @axlair/jupyterlab_vimをインストールしています。 なお、ローカルでdocker imageをビルドする際に当初jupyter lab buildを実行すると このissueと同じようにensure-max-old-space実行時にエラーが出てbuildできなくなりましたが、 osx上でDockerが使用するメモリを4096MBにしたところエラーが生じなくなりました。

コードの監視

jlpm run watchでextensionのコードに変更があるとすぐにrecompileしてくれるようになります。 またjupyterlabをjupyter lab --watchとして立ち上げるとその変更を監視しアプリケーションに取り込んでくれるようになります。 しかし手元ではwebpackがファイル監視に使用しているchokdairを見つけられないというエラーで動作しないため一旦諦めました。 なお、上記watchを施さなくてもjupyterlab自体をreloadするとコードに変更があった場合はbuildを促されるので大きな問題は生じませんでした。

※7/8追記: この監視がうまく行かない件ですがこのissueによればv2.1.3のバグとのことでv2.1.4にjupyterlabのバージョンを上げたら解決しました。

コードの構造

自動生成されたコードのsrc/index.tsを見ると主に3つのデータ構造を含んでいます。

• OutputWidgetクラス
  • 指定したMIMEタイプのデータを受け取りHTML DOMノードの中にどのように描画するのかを扱うクラス
  • extensionのほとんどのロジックを含む
• rendererFactoryオブジェクト
  • OutputWidgetクラスのインスタンスをどのようにアプリケーション内で生成するのかを扱うクラス
• extensionオブジェクト
  • extensionのメインのエントリーポイントとなる部分
  • jupyterlabがextensionをロードする際に必要となるメタデータを書く

コードの編集

下記編集を実施します。

• OutputWidgetのリネーム
  • src/index.ts内のOutputWidgetをWavWidgetへとリネームします(2箇所)
• extensionオブジェクトのfileTypesとmodelNameにbase64エンコードを指定
  • デフォルトだとプレーンテキストとして読もうとするのでbase64エンコードされたものとして読むための指定を追記
  • fileTypeにfileFormat: 'base64'、documentWidgetFactoryOptionsにmodelName: 'base64'を追加する
• レンダー方法の指定
  • WavWidgetクラスを編集
    • コンストラクタにaudioタグを追加するためのコードを追加
    • renderModelメソッド内でaudioタグのsrcを指定

大した量ではないためコード全体を下記に記します。

import { IRenderMime } from '@jupyterlab/rendermime-interfaces';



import { Widget } from '@lumino/widgets';

/**
 * The default mime type for the extension.
 */
const MIME_TYPE = 'audio/wav';

/**
 * The class name added to the extension.
 */
const CLASS_NAME = 'mimerenderer-wav';

/**
 * A widget for rendering wav.
 */
export class WavWidget extends Widget implements IRenderMime.IRenderer {
  /**
   * Construct a new output widget.
   */
  constructor(options: IRenderMime.IRendererOptions) {
    super();
    this._mimeType = options.mimeType;
    this.addClass(CLASS_NAME);
    /* 追加 */
    this._audio = document.createElement('audio');
    this._audio.setAttribute('controls', '');
    this.node.appendChild(this._audio);
  }

  /**
   * Render wav into this widget's node.
   */
  renderModel(model: IRenderMime.IMimeModel): Promise<void> {

    let data = model.data[this._mimeType] as string;
    /* 元コードを削除し下記を追加 */
    this._audio.src = `data:${MIME_TYPE};base64,${data}`

    return Promise.resolve();
  }

  private _audio: HTMLAudioElement;
  private _mimeType: string;
}

/**
 * A mime renderer factory for wav data.
 */
export const rendererFactory: IRenderMime.IRendererFactory = {
  safe: true,
  mimeTypes: [MIME_TYPE],
  createRenderer: options => new WavWidget(options)
};

/**
 * Extension definition.
 */
const extension: IRenderMime.IExtension = {
  id: 'jupyterlab-wav:plugin',
  rendererFactory,
  rank: 0,
  dataType: 'string',
  fileTypes: [
    {
      name: 'wav',
      fileFormat: 'base64',  // 追加
      mimeTypes: [MIME_TYPE],
      extensions: ['.wav']
    }
  ],
  documentWidgetFactoryOptions: {
    name: 'JupyterLab wav viewer',
    primaryFileType: 'wav',
    modelName: 'base64',  // 追加
    fileTypes: ['wav'],
    defaultFor: ['wav']
  }
};

export default extension;

上記コードを再度ビルドしてjupyterlabを再読み込みすれば完了です。

実際の表示の例

左のファイルブラウザからwavファイルをダブルクリックすると下記のようにaudio要素が表示されます。

ちなみにwavファイルを右クリックして表示される「Open in New Browser tab」を実行するとこのExtensionがなくてもブラウザの別タブで再生は元々可能です。

npmjsへの投稿

Extension Developer GUidのShipping Packagesの項を読むと extensionは単一のJavascriptパッケージであり、npmjs.orgから配布できることや、 jupyterlab-extensionというキーワードがpackage.jsonに含まれている場合JupyterLabのextension managerが見つけ出すことができるとの記載があります。 このキーワードはcookiecutterで自動生成された場合既に含まれているため、自ら追加する必要はありません。

よってnpmjs.orgへと登録することを考えます。 まずコマンドラインからnpmjsにログインしておきます。

$ npm adduser  # ユーザをnpmjs上に作成していない場合
$ npm login

次にpackage.jsonを編集し、nameの値をjupyterlab-wavから@wrist/jupyterlab-wavというように@username/extension-nameへと変えます。 更に必要に応じてhomepage、license、repositoryなどのフィールドを追加します。

最後に、README.mdを編集してjupyter labextension installの部分を@wrist/jupyterlab-wavのように変更します。

上記を終えたら下記でnpmjsへとアップロードして終了です。

$ npm publish --access=public

無事にhttps://www.npmjs.com/package/@wrist/jupyterlab-wavへとアップロードされていれば、以後

$ jupyter labextension install @wrist/jupyterlab-wav

と打つことでインストールできるようになります。 実際に新規にコンテナを生成し直して上記を試したところ使えるようになりました。

今後

• 他のMIMEタイプにも対応させる
  • 人によってはmp3も同様に開きたいこともあるかもしれませんが、MIME_TYPEの部分が配列になっていることから複数拡張子に対して同じような実装を使いませせるような気がしています
• Web Audio APIを用いて波形描画やスペクトログラムを描画する