[project] WASM compatibility for QuantEcon Lectures

[mmcky]

This project is to review and recommend changes that need to be made to:

• QuantEcon lectures
• QuantEcon.py package

that will help us better use and support the upcoming WASM environments such as those provided by JupyterLite.

Aim: To focus on https://github.com/quantecon/lecture-python-intro and identify solutions with the aim to enable the entire lecture set to run in the browser via WASM. If this aim is not fully achievable due technical restrictions -- we need to document all those cases and identify solutions.

TimeFrame: This lecture set will be used to support the QuantEcon Africa workshops that will be run in the first two weeks of July 2023

Date	Milestone
15th May 2023	Complete review of lecture series dependencies and report compatibility
01st June 2023	QuantEcon.py compatibility implemented and/or a sub-package available for the lecture series (in the short term)

Tasks include:

• install https://jupyterlite.readthedocs.io/en/latest/ and setup some instructions to build a common environment so those working on this project use the same baseline.
• review https://github.com/quantecon/lecture-python-intro and build a full dependency list to support lectures execution (not the build environment).
• review dependencies (i.e. numba) to see what is compatible
• for any incompatible dependencies we need to identify a solution to support execution in the browser (first best) or alternatives for running that lecture in colab (second best).
• can we implement a decorator in QuantEcon.py that is context driven, such that in a WASM environment numba jit is not used (if not supported)

Resources

The jupyterlite project

• setup custom jupyterlite on gh-pages for testing and construct a test bed that we can all work on together.
• see if jupyterlab-myst is runnable to render full myst notebooks
• load test notebooks (myst or download notebook set)

[mmcky]

It looks like graphviz is not currently supported in jupyterlite

xflr6/graphviz#197

[Smit-create]

@mmcky Thanks for the detailed setup. This looks promising.

can we implement a decorator in QuantEcon.py that is context driven, such that in a WASM environment numba jit is not used (if not supported)

I think numba has a flag(I guess DISABLE_JIT) which will just return python functions and should work for our case.

[jstac]

Thanks @Smit-create , sounds promising.

Please keep @oyamad included in any decisions that involve QuantEcon.py

[mmcky]

Please keep @oyamad included in any decisions that involve QuantEcon.py

Thanks @jstac -- for sure.

@Smit-create I have now create a project repository where we can deploy jupyterlite into gh-pages and share a common test environment. We can also document our findings in Issues and/or Wiki pages.

https://github.com/QuantEcon/project.lecture-wasm

[Smit-create]

pyodide currently has the supported list of packages given here: https://pyodide.org/en/stable/usage/packages-in-pyodide.html

Now, since this doesn't support numba, we won't be able to use quantecon (not even install it using piplite) as it's dependent on it.

So, here's one thing that comes to my mind with minimal changes in Quantecon.py:

1. Remove numba from its dependency list.
2. Instead of raising an error for numba not present, we can add a fallback by creating a wrapper module with a function, let's say qe_jit which will return numba jitted function in case numba is present, or else, just return pure python function. Also, we will raise a slight warning while loading quantecon that "Numba is not present, some computations may take longer time or may fail in same cases.". So something like this:

# We have function in qe.utils

def qe_jit(func, ...):
    if NUMBA_PRESENT:
        return numba.njit(func,...)
   else:
       return func

And remove this error message completely: https://github.com/QuantEcon/QuantEcon.py/blob/67fe7044148f95dbad42f85c82e288c7c1584650/quantecon/__init__.py#L8-L14

That is replacing all the numba decorators with wrappers.

This will open the doors for our lectures to be dependent on quantecon and some piplite-installable libraries.

[jstac]

Thanks @Smit-create , sounds promising.

Once @mmcky has reviewed this idea, let's run it by @oyamad .

[Smit-create]

Thanks @jstac.

There's one more way to handle this, but that might be kind of hack-ish or repetitive. We can create a new fork Quantecon.py focusing just on the methods/classes that are required to run the introductory series. The only drawback of this approach is that it limits the scope of moving other lecture series to jupyterlite. But for getting started, we can go by this route if we don't need much effort to get the introductory series running.

[mmcky]

@Smit-create that is exactly the sort of approach I was thinking as well use a decorator that could either return a jitted, jax, or plain python version of the function based on either a context flag or some other trigger.

[oyamad]

I am not very enthusiastic about the idea of allowing quantecon to run without Numba.

• Some functions in quantecon are useless without Numba, e.g., those for which functions of the same functionality exist in SciPy, such as linprog_simplex. Users who are not careful enough may install quantecon without Numba and conclude that some functions are too slow, which could deteriorate the reputation of quantecon.
• Adding a custom decorator would complicate the code and lead to a barrier to new contributors.
• I rather like the idea of creating a new fork, say quantecon-lite.

[jstac]

Thanks for your comments @oyamad. You make good points.

The key issue is how we make live lectures available to students. One option is via something like Google Colab, which is server-based. Another is distributed computing in the browser via WASM. The second option prohibits us using Numba.

I quite like Colab but it's rather dangerous to completely rely on a service over which we have no control.

On the other hand, using WASM degrades the quantecon library, as you say.

And of course WASM doesn't make GPUs available, unlike Colab.

So anyway, we have to choose between imperfect options.

(For background, @sglyon is leading a project to develop a learning management system (for workshops and teaching) that integrates WASM. QuantEcon has invested in that project.)

[sglyon]

I like the idea of QuantEcon-lite. We'll want to do what we can to minimize drift between QuantEcon.py and QuantEcon-lite

I think one way to do this would be to migrate all code to QuantEcon-lite, but remove numba parts. Then QuantEcon.py could depend on QuantEcon-lite, import the routines, and re-wrap them in numba/jax/etc. depending on context.

[mmcky]

(Just a side note) This is still very new and in development but this project may be able to target different contexts such as WebAssm, LLVM accelerated code, GPU etc.

---

@oyamad @jstac thanks for your comments. I agree the library wouldn't function well without the acceleration (in the wasm context for some functions), but we wanted to understand which functions are needed for lecture-python-intro (to test if this lecture series could run fully in WASM) and then document the trade-offs.

The current aim for this project is around compatibility and not performance at the moment to support a training/learning context (rather than a research one). If that makes some functions completely unusable then that is going to be a problem for sure, but we might be able to reduce the dimensionality of the problem for training context (as a tradeoff)?

@oyamad your idea of quantecon-lite is also a good one -- just need to think through code duplication issues. I think @sglyon suggestion is also an interesting suggestion to reduce this issue. Will 🤔

[Smit-create]

Here's a small demo: https://smit-create.github.io/qe-wasm-demo/. It has just one lecture on cobweb and that works completely fine. Hence, we have a working demo.

The above demo uses a hardcoded cobweb notebook.

In order to automate this, we can write a python script:

1. That fetches the lectures from the repository.
2. Converts them to the notebook using jupytext and serve them.

The above tasks seem to be easygoing. We need to figure out the following:

1. Make this work with jupyterlab extensions and fix exercises theme.
2. How to produce exact same notebook as jb so that it can link myst tags cite, exercise, etc?
3. Once everything is working and setup, how to test that all the lectures and running fine with no errors?

[jstac]

Thanks @Smit-create , very cool!!

[Smit-create]

I have written a script to automate updating the lectures (requires just a small manual effort of updating locally and pushing which can be automated later using gh-actions). The demo repo is: https://github.com/Smit-create/qe-wasm-demo.

For the next steps, let's plan to test all the notebooks manually(as discussed in yesterday's meeting) so that we can check both code errors and jupyterlab-myst rendering error (less priority than the code error).

1. If the lecture throws some error, please open up an issue specific to each lecture here: https://github.com/QuantEcon/lecture-python-intro. We will try to fix each of them one by one in the main repository itself.
2. Let's try to modify existing lectures that use libraries that aren't compatible with pyodide (Checking this is easy -- just open up any notebook from demo and try running %pip install library_name. If that passes and import library_name is okay, we can have that library or else need to find an alternative).

[mmcky]

thanks @Smit-create

The quantecon package issue is definitely failing with the following error message

ValueError: Can't find a pure Python 3 wheel for 'numba>=0.49.0'.

so perhaps we should try to address this global issue first as it will be common across a lot of lectures.

[Smit-create]

Thanks @mmcky, so to resolve that issue, as from the above discussion we have two options:

• jit wrappers in existing quantecon package.
• create a new quantecon-lite package.

I'm fine with any of them and will fix that according to whichever is chosen.