CASTOR Exposure Time Calculator (ETC)

FORECASTOR Team - 2022-2023

This package is under active development. It should be stable but please let me know if there are any bugs or unusual behaviour!

This Python package is an exposure time calculator for CASTOR. Since CASTOR is currently in Phase 0, this tool contains tunable parameters that are not normally exposed in most other exposure time calculators; the user is highly encouraged to read the docstrings and view the example notebooks prior to using this software. Likewise, there may be frequent updates to this package as the mission matures (see the changelog for more details).

Table of Contents

1. Launching on CANFAR
2. Installation
3. Building the Docker image for CANFAR/local machine
4. Viewing CANFAR Jupyter notebook session logs and Other Terminal Commands
5. Getting started and specific use-case examples: See the ETC_notebooks repository containing examples in Jupyter notebooks.
6. The browser-based graphical user interface to complement this ETC is located in the ETC_frontend repository.
7. Known issues
8. Roadmap
9. Questions, Issues, Suggestions, and Other Feedback

Launching on CANFAR

1. Ensure you have a Canadian Astronomy Data Centre account (or request one if you do not have one yet).
2. Go to CANFAR and sign in to the Science Portal. If you cannot access this, then you must send an email to support@canfar.net requesting access to the Science Portal.
3. Inside the Science Portal, click the "+" icon to launch a new session. Under "type", select "notebook". If multiple castor_etc versions are available, you can select the specific version you would like to use under the "container image" field. The version number is denoted by the string following the colon (e.g., images.canfar.net/castor/castor_etc:1.0.0 means version 1.0.0 of the castor_etc notebook image).
4. Assign a name to your Jupyter notebook container and choose the maximum amount of memory (RAM) and maximum number of CPU cores you would like to have available for your notebook container. Note that RAM and CPU are shared resources. A reasonable amount to use, for example, would be 16 GB of RAM and 4 CPU cores. Larger RAM and CPU requests are not uncommon, but please be mindful of others using the Science Portal.
5. Click the blue "Launch" button to start your new castor_etc notebook session. It can take up to a minute to launch the session depending on which computing node you are assigned to and the last time the image was launched. Additionally, only 1 session of each type is allowed at a time and they automatically shut down after 14 consecutive days.
6. The JupyterLab environment is set up to work "out of the box" with the castor_etc Python package. You do not need to install the castor_etc package separately; everything is running inside a conda environment. In addition to LaTeX, other convenience tools like git are preloaded as well. Feel free to suggest any changes to the default configuration.

Installation

If you do not wish to clone the repository, the easiest way to install the castor_etc package is via:

pip install git+https://github.com/CASTOR-telescope/ETC.git

Note that executing this command in a conda environment (i.e., by building from the environment file) is recommended.

Alternatively, after cloning this repository via:

git clone https://github.com/CASTOR-telescope/ETC.git

You can then install the ETC package using one of the following commands, which should be executed within the repository folder (i.e., ETC/).

To install the castor_etc package "normally", use either:

pip install .

or

python setup.py install

If you want to install in develop mode, use:

pip install -e .

In develop mode, the installation of the package simply links back to the castor_etc folder itself, meaning any changes made to this package will be reflected in your environment.

If you are doing transit simulations, then after installing the Python package, you will need to download these stellar models into a directory. When you are using getStarData() or use_gaia_spectrum() in spectrum.py and when you are using the Observation class in transit.py, you will need to set the stellar_model_dir parameter in these functions/class to the directory containing the stellar models on your local machine.

Known Issues

• Rectangular aperture sometimes produces the incorrect number of pixels in the photometry aperture. I believe this is actually a bug in astropy since the elliptical aperture does not suffer from this problem and the aperture weights are clearly wrong (see the photometry source code for an example that highlights this flaw).
  • The package will raise a warning when the number of aperture pixels is incorrect (i.e., when it deviates by more than 0.1 pixels from the true value). When this happens, either slightly change the aperture dimensions or avoid using the rectangular aperture for now.

Roadmap

Here are some future plans for the ETC:

• Use a sampled PSF to create a pixel-based kernel to convolve with the simulated images. Additionally, point sources should use the sampled PSF to calculate its encircled energy (we currently assume the point source PSF is a Gaussian).
• Add slitless grism and multi-object spectroscopic capabilities to the ETC
• Arbitrary source profiles (i.e., surface brightness profiles) based on a FITS file with spectrum? Not sure what I would be asking the user for in this case (e.g., what unit should the FITS file data be in?)... Please let me know if you have any ideas!
• Support simulating multiple sources within the same aperture (e.g., a point source on top of a galaxy).
• Make unit tests and implement continuous integration.

Important: do not hesitate to reach out (using one of the methods detailed below) if there are any features you would like the ETC to have. This tool is meant to be used by the community, after all!

Questions, Issues, Suggestions, and Other Feedback

Please reach out if you have any questions, suggestions, or other feedback related to this software—either through email (isaac.cheng.ca@gmail.com) or the discussions page. You can also ping me on Slack or even set up an online video/audio call! Larger issues or feature requests can be posted and tracked via the issues page. Finally, you can also reach out to Dr. Tyrone Woods, the Science Planning Tools Lead for CASTOR.