Using Jupyter to Run Example Notebooks#

Tip

You can run the notebooks in the cloud using Binder, no installation required! Just click on the Binder link found at the top of each runnable notebook.

Installing jupyter and setting up the kernel#

If you wish to locally run the notebooks, you will need to install jupyter, ipywidgets, and (for some of the notebooks) torchvision. There are two or three possible ways of getting a local jupyter install working with this package, depending on what tool you are using to manage your virtual environments and how you wish to handle them (see Installation for how to use conda or pip and venv to setup a virtual environment and install plenoptic).

Hint

If plenoptic is the only environment that you want to run notebooks from and/or you are unfamiliar with virtual environments, go with option 1 (for either conda or pip and venv).

  1. Install jupyter in the same environment as plenoptic. This is the easiest but, if you have multiple virtual environments and want to use Jupyter notebooks in each of them, it will take up a lot of space.

    $ conda activate plenoptic
$ conda install -c conda-forge "jupyterlab>=4.5" ipywidgets torchvision "jupyterlab_myst>=2.6"

    With this setup, when you have another virtual environment that you wish to run jupyter notebooks from, you must reinstall jupyter into that separate virtual environment, which is wasteful.

  2. Install jupyter in your base environment and use nb_conda_kernels to automatically manage kernels in all your conda environments. This is a bit more complicated, but means you only have one installation of jupyter lab on your machine:

    $ # activate your 'base' environment, the default one created by conda/miniconda
$ conda activate base
$ # install jupyter lab and nb_conda_kernels in your base environment
$ conda install -c conda-forge "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
$ conda install nb_conda_kernels
$ # install ipykernel, torchvision in the plenoptic environment
$ conda install -n plenoptic ipykernel torchvision

    With this setup, you have a single jupyter install that can run kernels from any of your conda environments. All you have to do is install ipykernel (and restart jupyter) and you should see the new kernel!

    Attention

    This method only works with conda environments.

  3. Install jupyter in your base environment and manually install the kernel in your plenoptic virtual environment. This requires only a single jupyter install and is the most general solution (it will work with conda or any other way of managing virtual environments), but requires you to be a bit more comfortable with handling environments.

    $ # activate your 'base' environment, the default one created by conda/miniconda
$ conda activate base
$ # install jupyter lab in your base environment
$ conda install -c conda-forge "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
$ # install ipykernel and torchvision in the plenoptic environment
$ conda install -n plenoptic ipykernel torchvision
$ conda activate plenoptic
$ python -m ipykernel install --prefix=/path/to/jupyter/env --name 'plenoptic'

    /path/to/jupyter/env is the path to your base conda environment, and depends on the options set during your initial installation. It’s probably something like ~/conda or ~/miniconda on Linux or MacOS and C:\Users\username\miniconda\ on Windows. See the ipython docs for more details.

    With this setup, similar to option 2, you have a single jupyter install that can run kernels from any virtual environment. The main difference is that it can run kernels from any virtual environment (not just conda!) and have fewer packages installed in your base environment, but that you have to run an additional line after installing ipykernel into the environment (python -m ipykernel install ...).

  1. Install jupyter in the same environment as plenoptic. This is the easiest but, if you have multiple virtual environments and want to use Jupyter notebooks in each of them, it will take up a lot of space.

    $ cd path/to/plenoptic
$ source .venv/bin/activate
$ pip install -e ".[nb]"

    $ source path/to/environments/plenoptic-venv/bin/activate
$ pip install "plenoptic[nb]"

    PS> cd path\to\plenoptic
PS> .venv\Scripts\activate
PS> pip install -e ".[nb]"

    PS> path\to\environments\plenoptic-venv\Scripts\activate
PS> pip install "plenoptic[nb]"

    With this setup, when you have another virtual environment that you wish to run jupyter notebooks from, you must reinstall jupyter into that separate virtual environment, which is wasteful.

  2. Install jupyter in one environment and manually install the kernel in your plenoptic virtual environment. This requires only a single jupyter install and is the most general solution (it will work with conda or any other way of managing virtual environments), but requires you to be a bit more comfortable with handling environments.

    $ source path/to/jupyter-env/bin/activate
$ pip install "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
$ cd path/to/plenoptic
$ source .venv/bin/activate
$ pip install ipykernel torchvision
$ python -m ipykernel install --prefix=path/to/environments/jupyter-env/ --name 'plenoptic'

    $ source path/to/environments/jupyter-env/bin/activate
$ pip install "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
$ source path/to/environments/plenoptic-venv/bin/activate
$ pip install ipykernel torchvision
$ python -m ipykernel install --prefix=path/to/environments/jupyter-env/ --name 'plenoptic'

    PS> path\to\environments\jupyter-venv\Scripts\activate
PS> pip install "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
PS> cd path\to\plenoptic
PS> .venv\Scripts\activate
PS> pip install ipykernel torchvision
PS> python -m ipykernel install --prefix=path\to\environments\jupyter-venv\ --name 'plenoptic'

    PS> path\to\environments\jupyter-venv\Scripts\activate
PS> pip install "jupyterlab>=4.5" ipywidgets "jupyterlab_myst>=2.6"
PS> path\to\environments\plenoptic-venv\Scripts\activate
PS> pip install ipykernel torchvision
PS> python -m ipykernel install --prefix=\path\to\environments\jupyter-env\ --name 'plenoptic'

    See the ipython docs for more details on this process.

    With this setup, you have a single jupyter install that can run kernels from any virtual environment. It can run kernels from any virtual environment, but that you have to run an additional line after installing ipykernel into the environment (python -m ipykernel install ...).

The following table summarizes the advantages and disadvantages of these three choices:

Method

Advantages

Disadvantages

  1. Everything in one environment

✅ Simple

❌ Requires lots of hard drive space

✅ Flexible: works with any virtual environment setup

  1. nb_conda_kernels

✅ Set up once

❌ Initial setup more complicated

✅ Requires only one jupyter installation

❌ Only works with conda

✅ Automatically finds new environments with ipykernel installed

  1. Manual kernel installation

✅ Flexible: works with any virtual environment setup

❌ More complicated

✅ Requires only one jupyter installation

❌ Extra step for each new environment

Running the notebooks#

Once you have jupyter installed and the kernel set up, you can download the tutorial notebooks and run them. Each notebook has a Download this notebook link at the top. After downloading, navigate to the directory containing the notebook, then run jupyter and open up the notebooks. If you did not install jupyter into the same environment as plenoptic, you should be prompted to select your kernel the first time you open a notebook: select the one named “plenoptic”.