Skip to content

Latest commit

 

History

History
148 lines (85 loc) · 8.6 KB

setup.md

File metadata and controls

148 lines (85 loc) · 8.6 KB
Raw

Software Setup

In order to be able to execute the notebooks with the tutorials, you should configure your workspace following one of the options below. We encourage the participants to test the following steps beforehand of the hands-on sessions.

The various options are listed in order of difficulty. However, whenever possible, we recommend the participants with some experience with Python environments to follow Option 3, installing the requirements on their laptops and executing the tutorial notebooks from there. This has the advantage of avoiding any possible issue with online servers, including unstable internet connection or uneven memory and server availability, both on Colab and on MyBinder.

Option 1: Google Colab

Easy (No software installation; Works for any OS)

Video instructions

  1. Visit https://colab.research.google.com

  2. Click the GITHUB tab

  3. Enter "gw-odw/odw-2021" in the search bar, and click enter to search

  4. Double click the notebook of your choice

  5. At the top of the notebook, uncomment any pip install commands by removing the #

    #! pip install -q 'gwosc==0.5.4 <-- Remove the # and run

    Warnings: a couple of warning messages are likely to show up, both of them are harmless.

    • Unrecognized runtime "igwn-py3#"; defaulting to "python3"

      This pop-up simply notifies you that this notebook has been created with a Python environment different than the default one of Colab. That's not a big deal because you will install all the missing dependencies with the command above.

    • WARNING: This notebook was not authored by Google.

      Same as before. Just close the pop-up and go ahead without worrying too much.

  6. Click run all from the runtime menu at the top

If you are not familiar with google Colab, you can beforehand take a look at the guides offered by Google at this link, in the "Examples" tab. In particular, it is recommended to have a certain understanding of the main features of notebooks, which you can learn in this tutorial.

Option 2: Run in mybinder

Easy (No software installation; Works for any OS)

Video instructions

Just click the button below

Binder

or visit mybinder.org, paste in the "GitHub repository name or URL" cell the following address https://github.com/gw-odw/odw-2021/, and hit the Launch button.

This will build a Docker image (if not already present) with the dependency file environment.yml. Then a JupyterHub server will be open hosting the contents of the gw-odw/odw-2021 repo. Check the Jupyter notebooks with the tutorials for the various days in the corresponding folders.

Option 3: You have a Linux or Apple/Mac computer -- Use conda

Intermediate (Some software installation; Will not work on Windows PC)

Video instructions

This workshop uses Python version 3.8. We recommend creating a Python virtual environment and install all the package dependencies there. The official environment with all the required packages is igwn-py38, available from the International Gravitational-Wave Observatory Network (IGWN) community website. However, we make available also a light-weight version of this environment, with only the strictly necessary packages to execute the notebooks. Whenever possible, we recommend the full installation though

This guide will walk you through the configuration of this environment with Conda.

  1. Install miniconda:

    You may need to restart your computer after installation.

  2. If you want to install the full igwn-py38 environment (recommended), download the YML dependencies file for the IGWN website:

    Instead, for the light-weight environment, download the YML file corresponding to your operating system from this repository:

    Note: the name of the light-weight environment is igwn-py38-lw to distinguish it from the official one, igwn-py38. In the following steps, remember to add the "-lw" subfix to the name.

  3. Add the conda-forge channel

    conda config --add channels conda-forge

  4. Create the environment.
    If you have downloaded the full environment, either on Linux or macOS:

    conda env create --file igwn-py38.yaml

    Otherwise, for the light-weight one:

    • On Linux: conda env create --file environment.yml
    • On macOS: conda env create --file igwn-py38-lw-macOS.yaml

  5. Clone the workshop git repo

    git clone https://github.com/gw-odw/odw-2021.git

  6. Move into the directory with the workshop git repo

    cd odw-2021

  7. Activate the environment.
    Note: remember to add "-lw" to the name of the environment if you have installed the light-weight one.

    conda activate igwn-py38

    (Light-weight environment: conda activate igwn-py38-lw)

  8. Build a custom jupyter kernel using the command

ipython kernel install --user --name=igwn-py38

or equivalently

python -m ipykernel install --user --name=igwn-py38

(Light-weight environment: --name=igwn-py38-lw)

  1. Start the Jupyter notebook server
    jupyter notebook and select the kernel igwn-py38 (igwn-py38-lw) if this is not done by default.

Notebooks: If you are not familiar with Jupyter notebooks, google one of the many introductory guides available on the internat, like this one. Also, taking a look at the Examples offered by Google Colab can be helpful.

Troubleshooting:

  • The kernel igwn-py38 should appear in the list returned by the command jupyter kernelspec list executed in a terminal
  • If, when you run jupyter, you get the message: Could not find kernel matching igwn-py38. Please select a kernel: Python 3 this indicates the igwn-py38 kernel is not installed properly. Make sure you executed step 9)
  • Having the full environment and the light-weight one with two different names allows them to coexist. If you want to leave the same name and overwrtite one or the other, simply add --force option when you create it.

Option 4: Linux install on Windows 10 with dedicated app (Windows 10 only)

Advanced (For Windows 10)

Install a Linux distribution on your Windows system. See instructions here: https://docs.microsoft.com/en-us/windows/wsl/install-win10

We suggest you install Debian GNU/Linux, which is the closest distribution to what is used currently by LIGO/Virgo. Once you have Linux installed, follow the instructions in Option 3.