The WFIRST team at STScI has developed an exposure time calculator, a PSF model, and an image simulator for the science community to plan how they will use WFIRST. These tools are available separately as the Pandeia exposure time calculator engine, the WebbPSF point spread function modeling package, and the Space Telescope Image Product Simulator (STIPS). Comprehensive setup documentation for local installation as well as tutorials for Pandeia and WebbPSF are provided here. STIPS is available at https://github.com/spacetelescope/STScI-STIPS. High level overviews of the functionality of the tools are available on STScI's WFIRST website.
To stay abreast of changes and make sure you always have the latest WFIRST simulation tools, you may wish to subscribe to our mailing list. This list is low-traffic and only for announcements.
Would you like to view the tutorial notebooks or install the simulation tools locally?
To cite our tools, we ask that you reference Pontoppidan et al. 2016, "Pandeia: a multi-mission exposure time calculator for JWST and WFIRST", Proc. SPIE. 9910. and/or Perrin et al. 2014, "Updated point spread function simulations for JWST with WebbPSF", Proc. SPIE. 9143..
The tutorials are stored as Jupyter Notebooks--documents which interleave code, figures, and prose explanations--and can be run locally once you have followed the setup instructions below. They can also be viewed in a browser.
- WebbPSF-WFIRST Tutorial — Simulate a PSF for the WFIRST Wide-Field Instrument by selecting a detector position. Evaluate PSF differences between two detector positions. Shows both the WebbPSF notebook GUI and a brief example of performing calculations with the API.
- Pandeia-WFIRST Tutorial — Calculate exposure times and simulate detector "postage stamps" for scenes made up of point sources and extended sources.
We have automated the setup of a temporary evaluation environment for community users to evaluate the WFIRST Simulation Tools from STScI. This depends on a free third-party service called Binder, currently available in beta (without guarantees of uptime).
To launch in Binder (beta), follow this URL: https://mybinder.org/v2/gh/spacetelescope/wfirst-tools/master (Note: If you see an error involving redirects in Safari, try Chrome or Firefox. This should be fixed soon by the Binder project.)
It may take a few minutes to start up. Feel free to explore and run example calculations. Launching an environment through Binder will always use the most recent supported versions of our tools.
Simulation products can be saved and retrieved through the file browser, but the environment is temporary. After a certain time period, the entire environment will be shut down and the resources returned to the cloud whence it came.
If you wish to save code or output products, you must download them from the Jupyter interface. (Or, better yet, switch to a local installation of the tools!)
-
Start by installing the free Docker Community Edition locally. This will make the
dockercommand available in your terminal. Note that after installing docker, you must open the application once for docker to be available from the command line. -
Clone this repository to a folder on your computer and
cdinto it. -
Execute
./run.shto build and start a Docker container. (The first time you build the container, you will have to download a lot of data files, but subsequent builds will be quick.) You should see a lot of output, ending with something like:[C 12:34:56.000 NotebookApp] Copy/paste this URL into your browser when you connect for the first time, to login with a token: http://localhost:8888/?token=aabbccddeeff00112233445566778899
Open that URL in a browser, and you'll see a Jupyter notebook interface to an environment with the tools available. (The run.sh script forwards localhost:8888 to the same port in the container, so you can copy the URL as-is.)
To stay abreast of changes and make sure you always have the latest WFIRST simulation tools, you may wish to subscribe to our mailing list. This list is low-traffic and only for announcements.
From time to time, we will release new versions of the tools or new notebooks. You can clone a fresh copy by following the instructions again, or use git pull from a terminal in the repository folder. (If you've run or modified your copies of the notebooks, you may want to make copies so your changes aren't clobbered. Use git checkout . to discard changes or git stash to temporarily stash them before git pull-ing.)
- Make sure you have Docker Community Edition installed correctly.
- Make sure to include the path to Docker in your
PATHenvironment variable. For example include the following line in your bashrc file:
If Docker is located in /usr/local/bin
export PATH=/usr/local/bin:$PATH
- Consult the Docker manual section on troubleshooting.
Sometimes you will see Successfully tagged wfirst-tools:latest in your terminal, but still get an error like this:
docker: Error response from daemon: driver failed programming external
connectivity on endpoint eloquent_lewin
(549b43e32ae795c446f14fd6408c72fe9ddf08dbb8bde1122c28299696eda064): Bind for
127.0.0.1:8888 failed: port is already allocated.
ERRO[0000] error waiting for container: context canceled
This means that port 8888 is already in use, either by a notebook server running on your computer, or by another Docker container. If you're pretty sure you aren't running anything on port 8888, you can use docker ps to see if the container is running:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
e4cb3f9a0cb1 wfirst-tools "tini -- start-not..." 3 minutes ago Up 3 minutes 127.0.0.1:8888->8888/tcp priceless_mirzakhani
You can use the name or container ID to stop it with docker stop:
$ docker stop e4cb3f9a0cb1
e4cb3f9a0cb1
And then run ./run.sh again.
The WebbPSF point-spread function model and Pandeia exposure time calculator engine are currently available for local installation by members of the science community. The required packages are distributed as part of Astroconda, a suite of astronomy-focused software packages for use with the conda package manager for macOS and Linux.
Astroconda depends on conda, a system that can manage multiple environments without letting packages in one clobber those in another. To accomplish this, it uses features of bash, the default shell on new Mac and Linux systems. Verify that you are running bash by running ps in a new terminal window and verifying that bash appears in the CMD column.
If you are using another shell, bear in mind that you must start a bash login shell (bash -l) to follow this guide and to run the simulation tools in a conda environment.
Commands for you to execute will be prefixed with a $. (You only need to type the part following the $.)
If you have already installed Astroconda, skip ahead to "Creating a WFIRST Tools environment".
The Getting Started instructions for Astroconda cover setting up the conda package manager and certain environment variables. Enable the Astroconda channel with the command conda config --add channels http://ssb.stsci.edu/astroconda (as explained in the Selecting a Software Stack document).
The WFIRST Simulation Tools suite includes Pandeia, an exposure time and signal-to-noise calculator that (for now) depends on Python 2.7. To create a Python 2.7 environment for WFIRST Simulation Tools, use the following command:
$ conda create -n wfirst-tools --yes python=2.7 numpy scipy astropy \
ipython-notebook ipykernel \
pyfftw pysynphot photutils \
webbpsf webbpsf-data
This will create an environment called wfirst-tools containing the essential packages for WFIRST simulations. To use it, you must activate it every time you open a new terminal window. Go ahead and do that now:
$ source activate wfirst-tools
You should see a new prefix on your shell prompt. (If the prompt was $ before, it should now look like (wfirst-tools) $.)
Next, create a new directory somewhere with plenty of space to hold the reference files and navigate there in your terminal (with cd /path/to/reference/file/space or similar).
To obtain the reference data used for synthetic photometry, you will need to retrieve them via FTP. The curl command line tool can be used as follows to retrieve the archives:
(wfirst-tools) $ curl -OL ftp://ftp.stsci.edu/cdbs/tarfiles/synphot1.tar.gz # 85 MB
(wfirst-tools) $ curl -OL ftp://ftp.stsci.edu/cdbs/tarfiles/synphot2.tar.gz # 34 MB
(wfirst-tools) $ curl -OL ftp://ftp.stsci.edu/cdbs/tarfiles/synphot5.tar.gz # 505 MB
This retrieves interstellar extinction curves, several spectral atlases, and a grid of stellar spectra derived from PHOENIX models. Extract them into the current directory:
(wfirst-tools) $ tar xvzf ./synphot1.tar.gz
(wfirst-tools) $ tar xvzf ./synphot2.tar.gz
(wfirst-tools) $ tar xvzf ./synphot5.tar.gz
This will create a tree of files rooted at grp/hst/cdbs/ in the current directory.
(Instructions for installing the full set of PySynphot reference data, including things like HST instrument throughput reference files, can be found in the PySynphot documentation.)
Pandeia is available through PyPI (the Python Package Index), rather than Astroconda. Fortunately, we can install it into our wfirst-tools environment with the following command:
(wfirst-tools) $ pip install pandeia.engine==1.2.1
Note that the ==1.2.1 on the package name explicitly requests version 1.2.1, which is the version that is compatible with the bundled reference data.
Pandeia also depends on a collection of reference data to define the characteristics of the WFIRST instruments. Download it (54 MB) as follows and extract:
(wfirst-tools) $ curl -OL http://ssb.stsci.edu/pandeia/engine/1.2.1/pandeia_wfirst_data-1.2.1.tar.gz
(wfirst-tools) $ tar xvzf ./pandeia_wfirst_data-1.2.1.tar.gz
This creates a folder called pandeia_wfirst_data in the current directory.
WebbPSF, Pandeia, and pysynphot all depend on certain environment variables to determine the paths to reference data.
You may wish to save these variables in your ~/.bash_profile file, or a new conda/activate.d/ script so they are always set when you go to run the WFIRST simulation tools.
Where you see $(pwd) in the following commands, substitute in the directory where you have chosen to store the reference data (e.g. echo "$(pwd)" becomes echo "/path/to/reference/file/space").
Configure the PySynphot CDBS path:
(wfirst-tools) $ export PYSYN_CDBS="$(pwd)/grp/hst/cdbs"
To test that pysynphot can find its reference files, use the following command:
(wfirst-tools) $ python -c "import warnings; warnings.simplefilter('ignore'); import pysynphot; print pysynphot.Icat('phoenix', 5750, 0.0, 4.5).name"
If you see "phoenix(Teff=5750,z=0,logG=4.5)" appear in your terminal, pysynphot and its reference data files have been installed correctly.
Next, configure the Pandeia path:
(wfirst-tools) $ export pandeia_refdata="$(pwd)/pandeia_wfirst_data"
To test that Pandeia can find its reference files, use the following command:
(wfirst-tools) $ python -c 'from pandeia.engine.wfirst import WFIRSTImager; WFIRSTImager(mode="imaging")'
If you do not see any errors, Pandeia was able to instantiate a WFIRST WFI model successfully.
In a terminal where you have run source activate wfirst-tools and set the above environment variables, navigate to the directory where you would like to keep the example notebooks and clone this repository from GitHub:
(wfirst-tools) $ git clone https://github.com/spacetelescope/wfirst-tools.git
This will create a new folder called wfirst-tools containing this README and all of the example notebooks. From this directory, simply run jupyter notebook. Choose Getting Started.ipynb from the file list, and explore the available examples of WebbPSF and Pandeia calculations.
Pandeia users are encouraged to address questions, suggestions, and bug reports to [email protected] with "Pandeia-WFIRST question" in the subject line. The message will be directed to the appropriate members of the Pandeia-WFIRST team at STScI. For issues with WebbPSF, we prefer that you report your issues in the GitHub issue tracker for the speediest response: https://github.com/spacetelescope/webbpsf/issues (choose the green "New Issue" button after logging in).
- WebbPSF documentation
- WebbPSF JWST quickstart notebook
- Perrin et al. 2014, "Updated point spread function simulations for JWST with WebbPSF", Proc. SPIE. 9143.
- How to use the ETC python code interface: JWST ETC Pandeia Engine Tutorial
- Pandeia tutorials on Space Telescope's GitHub
- Pontoppidan et al. 2016, "Pandeia: a multi-mission exposure time calculator for JWST and WFIRST", Proc. SPIE. 9910.