Install From Git

If you are downloading the code from scratch, please follow the instructions below. If you had already downloaded version 1 of the code and are switching to version 2, please see Switching from version 1 (PyPopStar) to version 2 (SPISEA).

SPISEA is hosted on GitHub. To begin, clone the git repository in your desired code directory:

git clone https://github.com/astropy/SPISEA.git

The main branch contains the current release, while the dev branch is for code development.

Dependencies

The basic SPISEA installation requires ~20 GB of memory, which is primarily for the suite of stellar evolution and atmosphere models. Other dependencies:

  • python (>=3.7; preferably via AstroConda, as it includes some necessary packages, like astropy and pysynphot)

  • astropy

  • pysynphot

  • scipy

  • numpy (>= v1.17)

  • matplotlib

  • pytest-astropy-header

  • STScI CDBS data package (See Set Up CDBS Directory below for instructions)

Build

Once the repository is cloned, you need to add SPISEA to your PYTHONPATH environment variable. For example, if you are using BASH, then you need to add the following line to your bash_profile:

export PYTHONPATH=$PYTHONPATH:<path_to_SPISEA>

where <path_to_SPISEA> is the location of the top-level SPISEA directory.

Set Up CDBS Directory

SPISEA uses the STScI CDBS infrastructure to store model atmospheres and HST filter throughputs. In particular, it expects a top-level cdbs directory with 3 sub-directories: comp, mtab, and grid. If you already have these set-up then you may proceed to the next section. Otherwise, follow the steps below.

  1. Create a cdbs directory on your machine:

    mkdir <your_path>/cdbs

  2. The CDBS files can be downloaded from this STScI website. Download the synphot1_throughput-master.tar and synphot5_pheonix-models.tar files and place them in your cdbs directory.

  3. Untar each of the files. Once completed, a new directory named grp will appear.

  4. The comp, mtab, and grid sub-directories SPISEA needs are under grp/redcat/trds/. Move these directories directly to <your_path>/cdbs.

  5. You may remove the (now empty) grp directory and the tar files if desired.

You should end up with a cdbs directory <your_path>/cdbs with sub-directories called comp, mtab, and grid. You will add additional atmosphere models to cdbs/grid in the Stellar Evolution and Atmosphere Models section below.

Stellar Evolution and Atmosphere Models

SPISEA requires grids of stellar evolution and atmosphere models in order to function. The evolution models are stand-alone and specific to SPISEA. The atmosphere model grids use the STScI CDBS conventions and should be placed in the cdbs/grid directory.

You will need to download 2 files:

You may optionally download a third file, which contains higher-resolution stellar atmospheres. Note that this file is quite large, and is not necessary for most SPISEA use cases:

SPISEA uses the low-resolution atmospheres (R = 250) in spisea_cdbs.tar.gz by default, as it is then much faster for synthetic photometry and is sufficient in most applications. However, the user can change this default; see Atmosphere Model Object for more details. Unless you change this default, spisea_cdbs_highres.tar.gz is not required.

Once downloaded, spisea_cdbs.tar.gz (and spisea_cdbs_highres.tar.gz, if desired) should be expanded in the cdbs directory. The output directories will automatically be placed in the correct locations. The spisea_models.tar.gz file can be expanded anywhere, though we recommend expanding it in the same location as your cdbs directory.

For example, if your cdbs directory is /<your_path>/models/cdbs/ then you should put the .gz files in /<your_path>/models/ and then unzip them from there:

cd /<your_path>/models/
tar -xvf spisea_cdbs.tar.gz
tar -xvf spisea_models.tar.gz

spisea_cdbs.tar.gz will put the model atmospheres in cdbs/grid, and spisea_models.tar.gz will put the evolution models in a new directory called evolution/

Set Paths to Models

You need to notify python where the evolution and atmosphere models live. This is done by setting two environment variables, PYSYN_CDBS and SPISEA_MODELS, to point to the cdbs and models directories (i.e. the directory where the evolution/ directory lives), respectively. For example, in your .bash_profile:

export PYSYN_CDBS=/<path_to_cdbs_directory>
export SPISEA_MODELS=/<path_to_models_directory>

Testing Your SPISEA Setup

If all goes well, you should be able to import any of the SPISEA functions an import statement like those at the top of the Quick Start Guide, such as:

from spisea import synthetic

You may get warnings that Extinction or thermal files are missing, such as:

UserWarning: Extinction files not found in /u/mwhosek/models/cdbs/extinction

UserWarning: No thermal tables found, no thermal calculations can be performed

However, these can be safely ignored since SPISEA doesn’t use those functionalities.

To further test your SPISEA install, try running the Quick Start notebook. It is also located in SPISEA/docs.

To test the full range of evolution models, atmosphere models, and photometric filters, run the test functions by going into the SPISEA/spisea directory and running:

pytest

Note that this uses the python pytest package. This will trigger the test functions we have implemented. If all is well, you shouldn’t get any errors. Warnings are (generally) fine.

TroubleShooting

If SPISEA is not properly in your PYTHONPATH, then when you try to import the SPISEA functions you will get an error message reporting No module named spisea.

If the SPISEA_MODELS or PYSYN_CDBS paths are broken, then SPISEA won’t know where to get the stellar models. When trying to import spisea/synthetic.py, you will get either or both of the following warnings:

UserWarning: PYSYN_CDBS is undefined; functionality will be SEVERELY crippled.

UserWarning: SPISEA_MODELS is undefined; functionality will be SEVERELY crippled.

Build and deploy from Docker

Build your own SPISEA image for Docker Containers. This installation form contains SPISEA deployed in a container and includes the data sets, models and all the necessary paths and code.

Requirements

  • Linux, Windows or MacOS with Docker installed.

  • At least 2 CPUs and 4 GB of RAM and 16 GB of storage.

Installation

To create the container image, clone this repository and build the container:

git clone https://github.com/astropy/SPISEA.git
cd SPISEA
docker build -t spisea .

Usage

To open a shell ready play with SPISEA:

docker run -ti spisea bash

To execute a script you have in your current folder:

docker run -ti -v $PWD:$PWD -w $PWD spisea  python myscript.py

Deploy from DockerHub

If you don’t want to build the image from scratch you can use a pre-build container image from DockerHub using the following commands:

docker pull amigahub/spisea:v1

Then, to open a shell ready to play with SPISEA:

docker run -ti amigahub/spisea:v1 bash

To execute a script you have in your current folder:

docker run -ti -v $PWD:$PWD -w $PWD spisea  python myscript.py

Deploy from Singularity containers

Download the image from DockerHub and convert it into a .sif image for Singularity.:

singularity pull spisea.sif docker://amigahub/spisea:v1

After downloading the image, you can use it in singularity by opening a shell on SPISEA image:

singularity shell spisea.sif