How to run WaterTAP with Jupyter notebooks

This guide describes the supported methods to work with WaterTAP using Jupyter notebooks.

Local (developer) installation

Important

These instructions assume that a WaterTAP developer environment has already been configured, as described in e.g. For WaterTAP developers.

Activate your WaterTAP environment. If your environment has a name different from watertap-dev, replace watertap-dev with the actual name wherever applicable:
```
conda activate watertap-dev
```
Navigate to the directory where your local clone of the WaterTAP repository is located
Run the following command to register the currently active WaterTAP environment as a Jupyter kernel. This will create a dedicated WaterTAP kernel that’s selectable in the Jupyter web interface, ensuring that the notebook code is run in the correct Python environment where WaterTAP is available.
```
python -m ipykernel install --user --name "watertap-dev"
```
Then, start the Jupyter server from the current directory, navigate to the desired notebook using the file browser, and launch it
If prompted to select a kernel, select watertap-dev from the menu. Otherwise, ensure watertap-dev appears in the kernel box in the top-right corner of the notebook interface

Online using Binder.org

Binder is an online service providing a short-lived temporary sandbox environment on public cloud resources where Jupyter notebooks can be run, free of charge, without having to install any software locally.

Click on this button to launch an environment pointing to the current main branch of the WaterTAP repository:

Important

A Binder environment is automatically destroyed after a few minutes of inactivity, which means that any unsaved progress will be lost. To avoid this, users should download a copy of a notebook file from the Binder environment to their local machine through the browser (in the Jupyter Lab file browser menu, right click on the notebook file, then Download). For more information, see https://mybinder.readthedocs.io/en/latest/about/about.html#how-long-will-my-binder-session-last.

Customization

Binder uses a Git repository hosted on, e.g., GitHub to fetch the notebooks and create the runtime environment. Users can specify a specific fork, branch, and Git ref (e.g., a particular commit hash), as well as the path to a particular directory or notebook file within the repository, that will be used when first starting the environment.

These options can be specified interactively on the Binder homepage, which will create a URL that can then be shared with others to generate a (separate) instance of the environment with the same repository settings.

Alternatively, the URL can be generated manually according to the following schema:

https://mybinder.org/v2/gh/<github-org-or-user-name>/<github-repo-name>/<git-ref>?labpath=<path-to-notebook>

Example, for branch mybranch of myuser’s fork of this repository, pointing to the tutorials/my-tutorial.ipynb notebook file:

https://mybinder.org/v2/gh/myuser/watertap/mybranch?labpath=tutorials/my-tutorial.ipynb