Wide Field Infrared Survey Telescope
WFIRST Tools Server

Introduction to the WFIRST Tools Server (JupyterHub)

STScI is providing a new tool called JupyterHub for running select WFIRST software tools, including WebbPSF and Pandeia. This provides the convenience of running calculations through a web browser on an STScI server that has the necessary software pre-installed. This removes the need to install software locally (although we do provide that as an alternative for WebbPSF).

Access to the JupyterHub server is offered upon request. Since the available software tools are presently in beta release, access is restricted to people connected to the WFIRST Project and Science Teams. Users are authenticated using a GitHub account. GitHub is an online service that is widely used in software development and other fields. GitHub offers free accounts, and these free accounts are currently how we authorize users. (For users that already have a GitHub account, the advantage is they do not need to maintain a separate username and a password just for the WFIRST Tools server.)

Important: JupyterHub currently works best with recent versions of the Firefox, Safari, and Chrome browsers. Internet Explorer is not currently supported by STScI for this tool.

Logging In

First, sign up for a free GitHub account at github.com, then send a message to help@stsci.edu with your name, institutional affiliation, the GitHub account name you chose, and a description of your connection to the WFIRST Project or Science Teams. Put "Request for WFIRST Tools server access" in the subject line to ensure your request is routed to the appropriate person. You will receive instructions from the helpdesk on the next steps.

Once your account is authorized and an account created for you, you may then visit https://wfirst-tools.stsci.edu/ and "Sign in with GitHub" when prompted (as shown in the figure below).

Note: if you logged out of GitHub earlier after signing up, ensure you are logged in to the main GitHub site at github.com before trying to connect to the WFIRST Tools server.

Screenshot of the login interface for the WFIRST Tools server

This will take you to a page at GitHub asking you to confirm you wish to use your GitHub account to log in to the WFIRST Tools server, shown below.

Screenshot of the GitHub authorization interface for the WFIRST Tools server

Click the "Authorize application" button to continue, and you will be presented with the WFIRST Tools server main page (shown in the figure below).

Screenshot of the WFIRST Tools server main page

First Steps in the Jupyter Interface

Once you have logged in, click on the "My Server" button to be taken to the list of demonstration notebooks (shown below).

Screenshot of the notebooks list visible on first login

Clicking on the filename of a notebook will open a new tab with its contents, as shown in the following screenshot.

Screenshot of the WebbPSF demonstration notebook

Demonstration notebooks provide a starting point for your own analyses, showing code that uses the WebbPSF-WFIRST or Pandeia toolkits to perform example calculations. Our demonstration notebooks include some basic instructions on using the Jupyter Notebook interface, but additional resources are available elsewhere online. If you have difficulties, consult the "Getting Help" section below first. If you still have questions, contact help@stsci.edu and mention that you have a question about Jupyter Notebooks on the WFIRST Tools server.

The "New" button above and to the right of the list will create a new Python 3 notebook. (A drop-down menu provides additional options, such as creating a file in the in-browser editor, or launching a terminal on the JupyterHub server.) User-created notebooks have access to the same libraries as the demonstration notebooks do.

Another way to get started with the notebook server is to duplicate an existing notebook. Select the checkbox next to a notebook name, and a new "Duplicate" button will appear as shown in the figure below. The duplicate notebook will appear in the list, and can be safely edited or renamed while keeping the original notebook for reference.

Screenshot of the notebooks list showing the "Duplicate" button

Getting Help

JupyterHub is very new technology, and the entire Jupyter project is moving very quickly. (For example: until recently, Jupyter Notebook was referred to as the IPython Notebook, and some documentation still uses the old name.) With that in mind, we have collected here some tips and tricks for getting oneself out of corners when computing with Jupyter Notebooks.

Should you have an issue that you cannot resolve with these tricks, please do contact help@stsci.edu and mention that you are asking about the WFIRST tools server.

Restarting a Kernel

If you've ever used Mathematica, this will be a familiar principle. Sometimes an interactive session in the notebook gets confusing, and you want to clear the defined variables and run the calculation afresh. The way to do this in the Jupyter Notebook is to select the "Restart" option from the "Kernel" menu, as shown in the figure below. Afterwards, you will have to re-import any packages you were using, and all defined variables will be cleared.

Screenshot showing the menu item for restarting a kernel

Resetting All the Demonstration Notebooks

In case you accidentally delete part of the demonstration notebooks that you really wanted to keep, or you just want to see the notebooks as they were when you first logged in, we provide the "! Reset notebooks to their original state.ipynb" notebook. It includes instructions on what will happen (overwriting all your local changes with a fresh copy), and a code cell you can run to reset the notebooks.

If the reset notebook is missing, you can make a new notebook, paste the following line in the first code cell, and run it with Shift-Enter:

That command will reset your notebooks to their initial state, overwriting any changes you have made locally.

Other Questions

For questions specific to the WFIRST tools (including WebbPSF, Pandeia, and the JupyterHub infrastructure at wfirst-tools.stsci.edu), contact the STScI helpdesk at help@stsci.edu. However, please keep in mind that these tools are being released in a beta form that may require some familiarity with Python for advanced uses.