Using Jupyter to Run Example Notebooks

Tip

You can run the notebooks in the cloud using Binder, no installation required!

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 and pooch . 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).

conda

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 ipywidgets torchvision pooch
   

   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 ipywidgets
   $ conda install nb_conda_kernels
   # install ipykernel, torchvision, and pooch in the plenoptic environment
   $ conda install -n plenoptic ipykernel torchvision pooch
   

   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 ipywidgets
   # install ipykernel and torchvision in the plenoptic environment
   $ conda install -n plenoptic ipykernel torchvision pooch
   $ 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. 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 ...).

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.

   Linux / MacOS

   plenoptic installed from source

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

   plenoptic installed from PyPI

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

   Windows

   plenoptic installed from source

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

   plenoptic installed from PyPI

   $ path\to\environments\plenoptic-venv\Scripts\activate
   $ 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.

   Linux / MacOS

   plenoptic installed from source

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

   plenoptic installed from PyPI

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

   Windows

   plenoptic installed from source

   $ path\to\environments\jupyter-venv\Scripts\activate
   $ pip install jupyterlab ipywidgets
   $ cd path\to\plenoptic
   $ .venv\Scripts\activate
   $ pip install ipykernel torchvision pooch
   $ python -m ipykernel install --prefix=path\to\environments\jupyter-venv\ --name 'plenoptic'
   

   plenoptic installed from PyPI

   $ path\to\environments\jupyter-venv\Scripts\activate
   $ pip install jupyterlab ipywidgets
   $ path\to\environments\plenoptic-venv\Scripts\activate
   $ pip install ipykernel torchvision pooch
   $ 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
Everything in one environment	✅ Simple	❌ Requires lots of hard drive space
	✅ Flexible: works with any virtual environment setup
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
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, navigate to plenoptic’s examples/ directory on your terminal and activate the environment you installed jupyter into, 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”.

Attention

If you did not install plenoptic from source, then you will not have the notebooks on your machine and will need to download them directly from our GitHub repo. If you installed plenoptic from source (and thus ran git clone), then the notebooks can be found in the examples/ directory.

ffmpeg and videos

Several methods in this package generate videos. There are several backends possible for saving the animations to file, see matplotlib documentation for more details. The default writer uses ffmpeg, which you’ll need installed and on your path in order to save the videos or view them in a jupyter notebook. Depending on your system, this might already be installed, but if not, and you’re using conda to manage your environments, the easiest way is probably through conda: conda install -c conda-forge ffmpeg.

To change the backend, run matplotlib.rcParams['animation.writer'] = writer before calling any of the animate functions. If you try to set that rcParam with a random string, matplotlib will tell you the available choices.