Home

Welcome to the iris Wiki

iris is a Python library to generate slab models of molecular emission in disks.

---

Table of Contents

1. Installation
2. Background
   2.1 Slab Models
   2.2 Keplerian Broadening
3. Crash Course
   3.1 Initial Settings
   3.2 Fetching HITRAN Data
   3.3 Making a Slab Model
   3.4 Compiling the Code
4. Examples
5. FAQ

---

Installation

Install the package via pip:

pip install iris-jwst

iris requires the following packages be installed beforehand: jax, pandas, astropy, astroquery

and Python >= 3.8

Background

Slab Models

With iris, the molecular emission lines are modeled using a slab technique, where the intensities are set by an average excitation temperature $(T_{ex})$, a column density ($N_{mol}$), and an emitting area $(A_{em})$. The population levels are assumed to be in Local Thermodynamic Equilibrium (LTE). That is, the excitation temperature and the gas kinetic temperature are assumed to be the same.

We assume the lines are Gaussians and have an intrinsic full-width-at-half-maximum $(\Delta V)$ which includes turbulent and thermal broadening. Note that $\Delta V$ is a free parameter set by the user.

iris generates an optical depth grid at a very high resolution ($\lambda / \delta \lambda \sim 10^6$) which is then used to calculate the opacity-weighted flux density. For each species, we estimate the total optical depth of lines $i=1,2,...,N$ as

$\tau (\lambda) = \sum_{i}^{N} \tau_{0,i} e^{(-(\lambda - \lambda_0)^2/2\sigma_{\lambda}^2)} $

where $\lambda_0$ is the rest wavelength of line $i$, $\sigma_{\lambda}$ is the line standard deviation $\left( \frac{\Delta V}{2\sqrt{2 \log 2}} \right)$, and the line-center optical depth is

$\tau_0 = \sqrt{\frac{\ln 2}{\pi}} \frac{A_{ul} N_{mol} \lambda_0^3}{4 \pi \Delta V} \left( x_l \frac{g_u}{g_l} - x_u \right)$.

Here $A_{ul}$ is the Einstein coefficient, $x_{l,u}$ the lower- and upper-level populations, and $g_{l,u}$ the lower- and upper-level degeneracies, respectively.

Setting a distance to the source of $d$, we can then compute the flux assuming emission from a Blackbody $B_{\nu}$ at temperature $T = T_{ex}$:

$F(\lambda) = \left(\frac{A_{em}}{d^2}\right) B_{\nu}(T) \left( 1 - e^{-\tau(\lambda)} \right)$.

The rightmost term above sets the final line profile, accounting for saturation effects at the line center:

The flux model is then post-processed by iris to a user-specified resolving power (R) and wavelength grid.

Keplerian Broadening

Optionally, we can go a step further and include the effects of Keplerian broadening on the line profiles. iris does this in 4 steps, which only add a couple milliseconds to the compute time:

1. Make a standard flux model $F_{\lambda}$ with turbulent+thermal broadening only.
2. Generate a flat, Keplerian disk model with inclination $i$, stellar mass $M_{*}$, innermost radius $r_{in}$, and outermost radius $r_{out}$.
3. Finely sample the line-of-sight velocities $v_{LOS} = v_{K} \sin(i) \cos(\phi)$ within the emitting region, where $v_{K} = (G M_{*}/r)^{0.5}$ is the Keplerian velocity and $\phi$ is the azimuthal angle. Make a normalized histogram ($k_{LOS}$) of $v_{LOS}$.
4. Convolve $F_{\lambda}$ with $k_{LOS}$.

The effects will be most noticeable for disks at high inclinations, very small inner radii, and/or with higher stellar masses.

Crash Course

Initial Settings

Whenever we work with iris, first we need to import jax in 64-bit mode. This is very important for the kind of calculations made by iris:

import jax 
jax.config.update("jax_enable_x64", True)

We can then import any other useful packages and iris itself:

import jax.numpy as jnp

import numpy as np
import matplotlib.pyplot as plt

import iris as iris
from iris import setup

Fetching HITRAN Data

The very first time we model a molecule, we need to download the corresponding HITRAN spectroscopic data. iris will do this for you. First we specify a path where we want the data to be downloaded, and then we use setup.setup_linelists to fetch and format the data:

path_to_moldata = './'  # path where we want to save the HITRAN data

# Get the data for H$_2$O and $^{13}$CO
setup.setup_linelists('H2O', 'H2O', 1, path_to_moldata)
setup.setup_linelists('13CO', 'CO', 2, path_to_moldata)

Note the signature of this function: the first argument is the isotopolog name, this can be whatever you want to name this species, e.g. '13CO' for $^{13} \text{CO}$. The second argument is the HITRAN main isotopolog name, this is the name for the main isotopolog in HITRAN, e.g. 'CO'. The third argument is the HITRAN isotopolog number, this is the ID number for the particular isotopolog of interest. For $^{13} \text{CO}$, the ID number is 2. You can easily find the ID numbers in the HITRAN website.

Making a Slab Model

1. Define a wavelength grid (in micron) to evaluate opacities. The spacing should correspond to an $R \sim 10^{5-6}$ or whatever is enough to sample the intrinsic line widths $\Delta V$ you want.

fine_wgrid = np.arange(11.5, 18.5, 1e-5)

2. Define a wavelength to downsample the final flux model. This will usually be the wavelength grid of your data.

obs_wgrid = np.arange(12.0,18.0,0.002)

3. Define the resolving power of the instrument

R = 3200

4. Initialize the slab object.

slab = iris.slab(molecules=['CO2', 'H2O'], wlow=11.0, whigh=19.0, path_to_moldata=path_to_moldata)

Compiling the Code

fff

Examples

...