=================================
Use mosaik with Jupyter Notebooks
=================================

You can use mosaik with Jupyter notebooks to have an interactive experience and to write or use tutorials or to document your steps. We have pre-created tutorials written in Jupyter notebooks which you can use. This page gives a short explanation on how to use those.

.. note:: Starting from version 3.2, mosaik uses asyncio, which does not support nested event loops natively. This leads to an error when using mosaik in a Jupyter notebook. Luckily, the issue can be resolved by installing the library `nest_asyncio <https://pypi.org/project/nest-asyncio/>`_ and calling

.. code-block:: python
   
   import nest_asyncio
   nest_asyncio.apply()

at the beginning of your notebook (before creating the mosaik ``World``).

**Step 1 - Use Jupyter in VS Code:** Jupyter notebooks can be used with different UIs. A simple approach is to use Visual Studio Code with its Jupyter extension. You can find detailed information on how to use Jupyter in VS Code in the `VS Code documentation <https://code.visualstudio.com/docs/datascience/jupyter-notebooks>`_.

**Step 2 - mosaik Jupyter repository:** Checkout our Jupyter notebook examples `repository <https://gitlab.com/mosaik/examples/mosaik-tutorials-on-binder>`_, e.g. via :code:`git clone https://gitlab.com/mosaik/examples/mosaik-tutorials-on-binder.git` and open the folder in VS Code.

**Step 3 - Virtual Environment:** Create a virtual environment with the requirements installed. See the following screenshots for an example on how to create a virtual environment.

.. figure:: /_static/tutorials/jupyter/1-kernel.png
   :width: 100%
   :align: center
   :alt: Choosing the kernel

   Choose the kernel.

.. figure:: /_static/tutorials/jupyter/2-venv.png
   :width: 100%
   :align: center
   :alt: Choosing to create a virtual environment

   Select the environment type. 

.. figure:: /_static/tutorials/jupyter/3-python.png
   :width: 100%
   :align: center
   :alt: Choosing the Python interpreter

   Select a python version to create a virtual environment.

.. figure:: /_static/tutorials/jupyter/4-requirements.png
   :width: 100%
   :align: center
   :alt: Choose to install the requirements

   Choose to install the requirements.

**Step 4 - Run a Jupyter notebook:** Choose one of the available notebooks, e.g., :code:`_02_simulator_mosaik.ipynb` and open it. You can now run the code blocks step by step or all at once with the "Run All" button on the top. Feel free to play with the example code, extend or change it to your needs or to create your own notebooks based on these examples.