Installation

There are a few avenues for installing PICASO (git, pip, or conda). To help determine which is best for you, we have a few questions to help you decide:

Are you a researcher who wants to stay up-to-date with the latest beta changes and contribute to the code base? Please follow the git clone instructions below.
Are you a student or researcher who just wants to get started with PICASO quickly and use it for science? Please follow the pip or conda install instructions below.
Do you want to use PICASO for an school assignment or workshop? Jump to the picaso-lite section of the Quickstart Notebook

Python >= 3.11 is recommended. It is also recommended you use environments (either conda or pip). Please check out our conda environment tutorial.

Users can 1) install from source or 2) install from pip or 3) conda

Install from source via git

The Github repository contains the reference folder and helpful tutorials.

git clone https://github.com/natashabatalha/picaso.git
cd picaso
pip install .

Install with Pip

pip install picaso

Install with conda

conda install conda-forge::picaso

Reference Data

PICASO has the ability to ingest lots of different kinds of data. But not all are required.

Only two are required:

The Reference Folder from Github and
the resampled opacity file which will let you do some basic spectral modeling.

Data Type	Req?	What it is primarily used for	Where it should go
Reference	Yes	everything	$picaso_refdata
Resampled Opacities	Yes	Spectroscopic modeling	$picaso_refdata/opacities/opacities*.db
Stellar Database	No	Exoplanet modeling	$PYSYN_CDBS/grid
Preweighted correlatedK Tables	No	Chemical equilibrium climate	Your choice (default=$picaso_refdata/opacities/preweighted)
By molecule correlatedK Tables	No	Disequilibrium climate	Your choice (default=$picaso_refdata/opacities/resortrebin)
Sonora grid models	No	Initial guess/grid fitting	Your choice (default=$picaso_refdata/sonora_grids)
Virga Mieff files	No	Virga cloud modeling	Your choice (default=$picaso_refdata/virga)

How to get Required Data

We outline here an easy way of getting the required data. These steps are also outlined in our Quickstart Notebook.

#using python
    import picaso.data as d
    #where do you want to store your reference data? This should be the path to the reference folder you downloaded from github.
    path_to_reference = "/path/to/picaso/reference/"
    d.os.environ['picaso_refdata'] = path_to_reference #only needed if you are using python to set your environment variables otherwise you do not need this
    #get required data 1) reference data
    d.get_reference(d.os.environ['picaso_refdata'])
    #get required data 2) resampled opacities
    d.get_data(category_download='resampled_opacity', target_download='default') #7Gb -- ENSURE STABLE WIFI!

Check it’s all good:

d.check_environ()

where the printout in a terminal will look something like this:

--- PICASO Environment Check ---
[INFO] Found picaso_refdata environment variable: /Users/nbatalh1/Documents/codes/PICASO/picaso/reference
[SUCCESS] Basic picaso reference data seems to be in place.
[INFO] Reference data version: 4.0
[INFO] Files in reference directory:
- input_tomls
- references
- stellar_grids
- config.json
- chemistry
- sonora_grids
- opacities
- version.md
- evolution
- scripts
- base_cases
- virga
- climate_INPUTS

Permanently Set Environment Variables

Setting environment variables help packages find data without having to set a path every time you run the code. Above we set the environment using python’s os.environ which is a temporary way to set environment variables.

You can feel free to continue using this non-permanent. If so, whenever you install picaso you would need to add this line to your code before you import picaso.

import os
os.environ['picaso_refdata'] = 'your_path/picaso/reference/' #THIS MUST GO BEFORE YOUR IMPORT STATEMENT
import picaso.justdoit as jdi

While this is the easiest way to set things up, it can become tedious to have to define this before every single notebook. If you want to permanently set your environment variables, see the next to subsections for some options that may suit your needs.

Permanent Method 1: `bash_profile` or `zshrc` file

As you might guess ~/.bash_profile is used for the Bash command line shell. ~/.zshrc is used for the Zsh command line shell. The steps below are identical.

vi ~/.bash_profile

Add add this line:

export picaso_refdata="/path/to/picaso/reference/"

Once you edit a bash profile file, you must source it. Alternatively you can open up a new terminal.

source ~/.bash_profile

If you have already downloaded reference data you can check that your variable has been defined properly:

echo $picaso_refdata
/Users/nbatalh1/Documents/codes/PICASO/picaso/reference
cd $picaso_refdata
ls
base_cases chemistry config.json evolution opacities version.md

Permanent Method 2: Add it to your conda environment

This is my method of choice! It involves creating conda environment specific variables. If you are interested in learning more about environment variables, you can read more about them here

If you already an environment setup, you can do the following – which mimics the bash_profile/method 1 example.

conda activate your_env_name
cd $CONDA_PREFIX
mkdir -p ./etc/conda/activate.d
mkdir -p ./etc/conda/deactivate.d
touch ./etc/conda/activate.d/env_vars.sh
touch ./etc/conda/deactivate.d/env_vars.sh

The env_vars.sh file is similar to your bash_profile file. Therefore you can directly add your export statement there.

vi ./etc/conda/activate.d/env_vars.sh

Now add the line:

export picaso_refdata="/path/to/picaso/reference/"

Finally, you want to make sure that your environment variable is unset when you deactivate your environment.

vi ./etc/conda/deactivate.d/env_vars.sh

unset picaso_refdata

Notice here that I do not have a tilda (~) in front of ./etc. The full path of the env_vars.sh should look something like this:

conda activate your_environment
cd $CONDA_PREFIX
cd ./etc/conda/activate.d/
pwd
/Users/nbatalh1/.conda/envs/picaso/etc/conda/activate.d

Getting Optional Reference Data

You can continue using get_data to get all additional data that you might need (see Quickstart Notebook for more examples). The most common one is the stellar grids for exoplanet modeling. The stellar grids are handled by another package called stsynphot and require the setting of an additional environment variable. Below we provide additional details on setting that up if needed.

Getting `stsynphot` Optional Stellar Data

In order to get stellar spectra needed for many exoplanet PICASO has already installed for you the stsynphot package which has several download options for stellar spectra. This package also requires setting an environment variable called $PYSYN_CDBS. Below are instructions for getting the stellar data manually and setting the environment variable (note you can also use picaso auto download to get these data).

The Default for PICASO is Castelli-Kurucz Atlas: ck04models but we recommend phoenix models for climate modeling.

Here is how you would do it with PICASO:

import picaso.data as d
d.os.environ['PYSYN_CDBS'] = d.os.path.join(d.os.environ['picaso_refdata'],'stellar_grids') #this is a path of your choosing
d.get_data(category_download='stellar_grids') #recommend downloading both ck04models and phoenix

As the default this will store your stellar grids in $picaso_refdata/stellar_grids. However, you can always choose a different path.

If you do not like that you can always use wget or just downloading the link below.

wget http://ssb.stsci.edu/trds/tarfiles/synphot3.tar.gz

When you untar this you should get a directory structure that looks like this <path>/grp/redcat/trds/grid/ck04models. The full directory structure does not matter. Only the last file grid is needed. You will need to create an environment variable that points to where grid/ is located. We have a nice placeholder location in the picaso reference data file for these grids $picaso_refdata/stellar_grids. So you can imagine something like: $picaso_refdata/stellar_grids/grid/ck04models. Though it is not required for you to put them here as long as you make your environment variable point to the desired location where grid is.

Help Permanently Setting Stellar Data Environment Variable

Similar to PICASO’s environment variable instructions, follow the same steps to create an environment variable for PYSYN_CDBS. PICASO recommends the path: PYSYN_CDBS=$picaso_refdata/stellar_grids but you might have this elsewhere.

We’ve gone over how to set permanent paths before but here is a quick refresher using the bash_profile method:

vi ~/.bash_profile

Add this line:

export PYSYN_CDBS="/your/path/to/picaso_refdata/stellar_grids"

Then always make sure to source your bash profile after you make changes.

source ~/.bash_profile

Now you should be able to check the path:

cd $PYSYN_CDBS
ls
grid

Where the folder grid/ contains whatever stsynphot data files you have downloaded (e.g. a folder called ck04models/).

Using Quickstart Notebook

If you are already very familiar with package installs, environment variables OR you are a student using PICASO for classwork you can jump straight to our Quickstart Notebook.