documents/userguide/exomol.rst
ExoMol
--------------
*Sep 5 (2021) Hajime Kawahara*
See ":doc:`../tutorials/opacity_exomol`" as the tutorial to compute a cross section profile using ExoMol.
Molecular Database
======================
`ExoMol <http://www.exomol.com/>`_ provides molecular line database of various molecules and also from various sources. For instance, they provide `multiple source of the line data of the carbon monoxide (CO) <http://www.exomol.com/data/molecules/CO/12C-16O/>`_. So, we need to specify which database you use.
exojax specifies the default database for each molecule. You can know by
.. code:: ipython
>>> from exojax.spec import defmol
>>> defmol.search_molfile("ExoMol","12C-16O")
'CO/12C-16O/Li2015'
An example to use the ExoMol database from exojax is like that.
.. code:: python
>>> from exojax.spec import moldb
>>> from exojax.utils.grids import wavenumber_grid
>>> nus,wav,res=nugrid(22880.,23000.,1000,unit="AA")
>>> mdbCO=moldb.MdbExomol('.database/CO/12C-16O/Li2015',nus)
Background atmosphere: H2
Reading transition file
Broadening code level= a0
default broadening parameters are used for 71 J lower states in 152 states
Broadening Parameters
======================
exojax uses .broad file as the broadening parameters. The comment
.. code:: python
Broadening code level= a0
means the broadening parameters as a function of the lower J-quantum number is used.
.. code:: python
default broadening parameters are used for 71 J lower states in 152 states
However, the broadning parameters are not often provided for higher J values. Instead, exojax uses the default values in .def file for them.
Vaex File Format
=====================
For the first time to load the Exomol database using :doc:`../exojax/exojax.spec` , exojax automatically converts the transition and state files into Vaex/HDF5 format.
.. code:: sh
penchan:~/exojax/data/CO/12C-16O/Li2015>ls -1
12C-16O__H2.broad
12C-16O__He.broad
12C-16O__Li2015.def
12C-16O__Li2015.pf
12C-16O__Li2015.states.bz2
12C-16O__Li2015.states.bz2.hdf5
12C-16O__Li2015.states.bz2.yaml
12C-16O__Li2015.trans.bz2
12C-16O__Li2015.trans.bz2.hdf5
12C-16O__Li2015.trans.bz2.yaml
The files with a suffix of "bz2.hdf5" amd "bz2.yaml" were generated by exojax. After the second time, exojax will use these HDF files, which significantly decrease the loading time. exojax also use .broad file for the broadening parameters.
Basic Quantities
==================
+-----------------------+-------------+----+------+
|**quantity** |**instance** |unit|np/jnp|
+-----------------------+-------------+----+------+
|line center |nu_lines |cm-1|np |
+-----------------------+-------------+----+------+
|line center |dev_nu_lines |cm-1|jnp |
+-----------------------+-------------+----+------+
|lower state energy |elower |cm-1|jnp |
+-----------------------+-------------+----+------+
|natural broadening |gamma_natural|cm-1|jnp |
+-----------------------+-------------+----+------+
|Einstein coefficient |A |s-1 |jnp |
+-----------------------+-------------+----+------+
|reference line strength|Sij0 |cm |np |
+-----------------------+-------------+----+------+
|log_e Sij0 |logsij0 | |jnp |
+-----------------------+-------------+----+------+
|statistical weight |gpp | |jnp |
+-----------------------+-------------+----+------+
|J_lower |jlower | |jnp |
+-----------------------+-------------+----+------+
|J_upper |jupper | |jnp |
+-----------------------+-------------+----+------+
|temperature exponent |n_Tref | |jnp |
+-----------------------+-------------+----+------+
|alpha_ref (gamma0) |alpha_ref | |jnp |
+-----------------------+-------------+----+------+
Exomol API
======================
`moldb.MdbExomol <../exojax/exojax.spec.html#exojax.spec.moldb.MdbExomol>`_ uses function in `exomolapi <../exojax/exojax.spec.html#exojax.spec.exomolapi>`_ to read the ExoMol files, to download if these file do not exist, and to compute some quantities.
Read .def file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The path to the def file should be given using pathlib.Path.
.. code:: python
from exojax.spec.exomolapi import read_def
import pathlib
deff=pathlib.Path("~/exojax/examples/luhman16/.database/CO2/12C-16O2/UCL-4000/12C-16O2__UCL-4000.def")
n_Texp, alpha_ref, molmass, numinf, numtag = read_def(deff)
Note that we have not check all the molecules in ExoMol database yet. In some case, there is inconsistency in the definition file and due to this inconsistency, one cannot load the ExoMol files. Let `me <http://secondearths.sakura.ne.jp/en/index.html>`_ know if you find that case.
Read the partition, states, transition files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For these files, the path can be just string.
.. code:: python
from exojax.spec.exomolapi import read_pf, read_states, read_transf
pff="~/exojax/data/exomol/CO/12C-16O/Li2015/12C-16O__Li2015.pf"
dat=read_pf(pff)
statesf="~/exojax/data/exomol/CO/12C-16O/Li2015/12C-16O__Li2015.states.bz2"
states=read_states(statesf)
transf="~/exojax/data/exomol/CO/12C-16O/Li2015/12C-16O__Li2015.trans.bz2"
trans=read_trans(transf)
Compute gup and Elower
^^^^^^^^^^^^^^^^^^^^^^^^^^
`exomolapi.pickup_gE <../exojax/exojax.spec.html#exojax.spec.exomolapi.pickup_gE>`_ picks gup and Elower for all of the transitions from quantum states.
.. code:: python
from exojax.spec.exomolapi import pickup_gE
A, nu_lines, elower, gup, jlower, jupper=pickup_gE(states,trans)
Read .broad file
^^^^^^^^^^^^^^^^^^^^^^^
`exomolapi.read_broad <../exojax/exojax.spec.html#exojax.spec.exomolapi.read_broad>`_ can read .def file. The broad file defines its algorithm to compute the broadening parameters. Curreny, we support a0 and a1 only. this level can be checked using `exomolapi.codelv <../exojax/exojax.spec.html#exojax.spec.exomolapi.codelv>`_. If codelv="a0", we can use `exomolapi.make_j2b <../exojax/exojax.spec.html#exojax.spec.exomolapi.make_j2b>`_. If codelv="a1", then use make_j2b first and then use `exomolapi.make_jj2b <../exojax/exojax.spec.html#exojax.spec.exomolapi.make_jj2b>`_. These functions provide mapping arrays from J values to alpha_ref and n_Texp. For instance, j2alpha_ref[1] gives alpha_ref for Jlower=1, and jj2n_Texp[1,2] gives n_Texp for Jlower=1, Jupper=2.
.. code:: python
from exojax.spec.exomolapi import read_broad, check_bdat
from exojax.spec.exomolapi import make_j2b, make_jj2b
broadf="~/exojax/data/broad/1H2-16O__H2.broad"
bdat=read_broad(broadf)
codelv=check_bdat(bdat)
print(codelv)
if codelv=="a0":
j2alpha_ref, j2n_Texp=make_j2b(bdat,jlower_max=100)
elif codelv=="a1":
j2alpha_ref, j2n_Texp=make_j2b(bdat,jlower_max=100)
jj2alpha_ref, jj2n_Texp=make_jj2b(bdat,j2alpha_ref,j2n_Texp,jupper_max=100)