\documentclass{article}

\usepackage{graphicx}
\usepackage{fancyhdr}

\makeindex{}

\makeatletter
\textheight 625pt
\textwidth 460pt
\oddsidemargin 0pt
\evensidemargin 0pt
\marginparwidth 50pt
\topmargin 0pt
\brokenpenalty=10000

% Makes fancy headings and footers.
\pagestyle{fancy}

\fancyhf{} % Clears all fields.

\lhead{\scshape Someone et al., 2014}
\rhead{\scshape \nouppercase{\rightmark}}   %
\fancyfoot[C]{\bfseries \thepage{}}

\renewcommand{\headrulewidth}{0pt}    %
\renewcommand{\footrulewidth}{0pt}    %

\renewcommand{\sectionmark}[1]{%
  \markright{\thesection. \MakeLowercase{#1}}}
\renewcommand{\subsectionmark}[1]{}

\newcommand{\ie} {{\em i.e.}}
\newcommand{\eg} {{\em e.g.}}
\newcommand{\cf} {cf.}

\newcommand{\linedb} {\mbox {\bf LINEDB}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{center}
    \includegraphics[width=5cm]{gildas-logo}\\[2\bigskipamount]
  \huge{}
  IRAM Memo 2014-?\\
  \linedb\\[3\bigskipamount]
  \large{}
  Author1$^1$, Author2$^{1,2}$\\[0.5cm]
  1. IRAM (Grenoble)\\
  2. Observatoire de Paris\\[\bigskipamount]
  \normalsize{}
  February, 25$^{th}$ 2016\\
  Version 0.2
\end{center}

\begin{abstract}
  TO BE FILLED
\end{abstract}

\newpage{}
\tableofcontents{}

\newpage{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Test}

\section{Providing your own database}

\linedb{} accepts building a local database with a custom list of
lines. This can be achieved through two ASCII files: 
\begin{enumerate}
\item the line ``catalog'' \eg\
\begin{verbatim}
     29005   NNH+
   93171.8800   .0400 -2.7844 2    0.0000  9 -29005 102 1 1         0 1
   93173.7000   .0400 -2.5625 2    0.0000 15 -29005 102 1 2         0 1
   93176.1300   .2200 -3.2614 2    0.0000  3 -29005 102 1 0         0 1
     30002   HC-13-O+
   86754.2884  0.0046 -2.2835 2    0.0000  3 -30002 101 1           0
\end{verbatim}
  This catalog must follow the JPL convention (in particular, column
  alignment) described in Appendix~\ref{app:jpl}. The lines must be
  gathered by species. Each group is identified by a first line
  providing the tag value and the species name. The latter should be
  limited to 32 characters because of internal limitations of the
  \linedb{} databases. There can be no blank nor comment lines in this
  file.

\item the \emph{partition function} file. It must be named {\tt
    partfunc.cat} and must use the following format \eg:
\begin{verbatim}
species      NNH+      29005
temperatures 300.   225.   150.   75.    37.5   18.75  9.375
qpart        3.0831 2.9586 2.7832 2.4842 2.1875 1.8952 1.6116

species      HC-13-O+  30002
temperatures 300.   225.   150.   75.    37.5   18.75  9.375
qpart        2.1599 2.0353 1.8598 1.5607 1.2637 0.9707 0.6859
\end{verbatim}
  The tag and species name should match the catalog ones. The number
  of temperatures/qpart pairs are free. Those three lines must be
  consecutive in the file, with one set of lines per species. There
  can be a custom number of blank and comment (!) lines between each
  set of lines.
\end{enumerate}

Given those files, importing them in \linedb{} is as easy as:
\begin{verbatim}
SIC> use in mybase.dat
I-USE,  mybase.dat (offline) selected with /(partfunc.json|partfunc.cat) for partition functions
SIC> select
I-SELECT,  4 lines found in the frequency range 0 to infinity MHz
SIC> list
  # Species        Freq[MHz] Err[MHz] Eup[K]  Gup  Aij[s-1]    Upper level -- Lower level    Origin
  1 HC-13-O+       86754.288   0.005     4.2    3  1.21e-05              1 -- 0              mybase.dat
  2 NNH+           93171.880   0.040     4.5    9  3.63e-05            1 1 -- 0 1            mybase.dat
  3 NNH+           93173.700   0.040     4.5   15  2.18e-05            1 2 -- 0 1            mybase.dat
  4 NNH+           93176.130   0.220     4.5    3  1.09e-04            1 0 -- 0 1            mybase.dat
\end{verbatim}

It is advised to save this catalog in the \linedb{} binary format,
\ie\ after the previous steps:
\begin{verbatim}
SIC> use out mybase.db
SIC> insert
\end{verbatim}

% ZZZ Questions by Arnaud Belloche 25-feb-2016
% Est-ce pour des raisons de rapidité d'accès aux données?
% Est-ce utile aussi lorsqu'on n'utilise que modsource ?


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Interfacing the CDMS via VAMDC}

As of 2016, February 24th, the Cologne Database for Molecular
Spectroscopy (CDMS) is in the process of moving its database to the
Virtual Atomic and Molecular Data Centre (VAMDC). For external users
(like LINEDB programmers and users), this implies several changes
exposed hereafter.

\subsection{Changes for end-users}

To first order, using the new protocol to query the CDMS database
should be transparent to the end user. This is one of the purpose of
\linedb. However, it seems that the database behind the new protocol
is not same as before. The user should be aware that:
\begin{itemize}
\item as of today, the request takes more time and more bandwidth than
  before (48 minutes to download the database in the range 100-400
  MHz, 893 MB in return),
\item the species name/formula may be different between the old and
  new database (e.g. ``Methanol'' vs ``CH3OH'', ``CCH, v=0'' vs
  ``CCH''),
\item the vibrational state has been removed from the formulas (see
  e.g. ``CCH'' above),
\item querying a formula may return the same molecule under different
  formulas (e.g. you ask for ``HCCCN'' and \linedb\ returns ``HCCCN''
  and ``HC3N''),
\item some lines seem to have disappeared in the new database
\end{itemize}

\subsection{Queries}

The new server supports TAP-VAMDC queries using VSS1 or VSS2
languages. The query may be as simple as:
\begin{verbatim}
  select *
\end{verbatim}
to retrieve the whole database, or for example
\begin{verbatim}
  select * where
  (RadTransFrequency >= 9.671000e+04 and RadTransFrequency <= 9.677000e+04) and
  RadTransProbabilityA >= 3.000000e-06 and
  InChiKey in ('TXKMVPPZCYKFAC-UHFFFAOYSA-N','OKKJLVBELUTLKV-UHFFFAOYSA-N')
\end{verbatim}
to retrieve the S2O and CH3OH lines ({\tt InChIKey}), between 96710
and 96770 MHz ({\tt RadTransFrequency}), which have an Einstein
coefficient above 3e-6 ({\tt RadTransProbabilityA}). Once the query
command is built, it is encoded in the whole HTTP url.\\

The list of supported restrictables (i.e. the parameters which can be
used for filtering) can be found in the VAMDC
documentation\footnote{See {\tt
    http://www.vamdc.eu/documents/standards/dictionary/restrictables.html}}. For
interfacing with the command {\tt SELECT}, \linedb\ uses the
restrictables shown in the Table~\ref{tab:restrictables}. {\tt
  RadTransFrequency} and {\tt RadTransProbabilityA} are direct
equivalent of the {\tt SELECT} filters. There is no restrictable for
selecting a line by its upper level energy ({\tt /ENERGY}), so the
filtering is performed internally in \linedb\ afterwards.

The {\tt /SPECIES} case is a more complex issue. \linedb\ uses the
molecule formula or name to identify a species. The equivalent in the
XSAMS format is the {\tt OrdinaryStructuralFormula} (see
subsection~\ref{txt:xsams} for details). However, because this
property can be an ambiguous reference to a species (e.g. ``Methanol''
and ``CH3OH'', ``HCCCN'' and ``HC3N''), it can not be used as a
filter. VAMDC offers instead the InChI (\emph{IUPAC International
  Chemical Identifier}\footnote{See {\tt www.iupac.org/inchi/}}) or
the InChIKey (hashed InChI) as non-ambiguous identifier. In practice,
\linedb\ has to know how to translate the formula as an InChIKey. This
is done by downloading and parsing the full {\tt Species} table (and
only this one) once at the beginning of the session. As of today this
table provides 734 species; they are listed in the
Appendix~\ref{app:species}.

\begin{table}[htb]
\centering
\caption{Look-up-table between the \linedb\ {\tt SELECT} options and
 the VAMDC restrictables.}
\vspace{1ex}
\begin{tabular}{ccl}
\hline
\hline
{\tt SELECT} option & Restrictable               & Comments \\
\hline
{\tt /SPECIES}      & {\tt InChIkey}             & Translation needed \\
{\tt /FREQUENCY}    & {\tt RadTransFrequency}    & [MHz] \\
{\tt /ENERGY}       &  N/A                       & Done internally in \linedb \\
{\tt /AIJ}          & {\tt RadTransProbabilityA} & [$s^{-1}$] \\
{\tt /ORIGIN}       & (not relevant)             & \\
{\tt /SORTBY}       & (not relevant)             & \\
{\tt /EPSILON}      & (not relevant)             & \\
\hline
\end{tabular}
\label{tab:restrictables}
\end{table}

\subsection{Parsing}
\label{txt:xsams}

In return of the VAMDC query, the server returns the filtered database
under the VADMC-XSAMS format (modified version of the \emph{XML Schema
  for Atoms, Molecules and Solids}\footnote{See {\tt
    http://vamdc.eu/documents/standards/dataModel/vamdcxsams/introduction.html}}). This
is basically an XML file providing several tables. \linedb\ is
interested in the {\tt <Species><Molecules>} table (which provides a
collection of {\tt <Molecule>} blocks) and the {\tt
  <Processes><Radiative>} table (which provide a collection of {\tt
  <RadiativeTransition>} blocks.

\subsubsection{Molecule description}

A typical example of a {\tt <Molecule>} is (truncated for clarity):
{\footnotesize
\begin{verbatim}
  <Molecule speciesID="XCDMS-132">

    <MolecularChemicalSpecies>
      <OrdinaryStructuralFormula>
        <Value>C-13-O-18</Value>
      </OrdinaryStructuralFormula>
      <StoichiometricFormula>CO</StoichiometricFormula>
      <ChemicalName>
        <Value>Carbon Monoxide</Value>
      </ChemicalName>
      <InChI>1S/CO/c1-2/i1+1,2+2</InChI>
      <InChIKey>UGFAIRIUMAVXCW-RGIGPVFXSA-N</InChIKey>
      <VAMDCSpeciesID>UGFAIRIUMAVXCW-RGIGPVFXSA-N</VAMDCSpeciesID>
      <PartitionFunction>
        <T units="K">
          <DataList>1.072 1.148 (truncated) 1000.0</DataList>
        </T>
        <Q>
          <DataList>2.05524705685 2.07536036351 (truncated) 798.466964704</DataList>
        </Q>
      </PartitionFunction>
    </MolecularChemicalSpecies>

    <MolecularState stateID="SCDMS-9240238">
      <MolecularStateCharacterisation>
        <StateEnergy methodRef="MCDMS-6647" energyOrigin="SCDMS-9240238-origin-132">
          <Value units="1/cm">0.0</Value>
        </StateEnergy>
        <TotalStatisticalWeight>2</TotalStatisticalWeight>
        <NuclearStatisticalWeight>2</NuclearStatisticalWeight>
      </MolecularStateCharacterisation>
      <Case>
        <dcs:QNs>
          <dcs:ElecStateLabel>X</dcs:ElecStateLabel>
          <dcs:v>0</dcs:v>
          <dcs:J>0</dcs:J>
          <dcs:F nuclearSpinRef="C-13">0.5</dcs:F>
        </dcs:QNs>
      </Case>
    </MolecularState>

    <MolecularState stateID="SCDMS-9240239">
      <MolecularStateCharacterisation>
        <StateEnergy methodRef="MCDMS-6647" energyOrigin="SCDMS-9240238-origin-132">
          <Value units="1/cm">3.492795</Value>
        </StateEnergy>
        <TotalStatisticalWeight>2</TotalStatisticalWeight>
        <NuclearStatisticalWeight>1</NuclearStatisticalWeight>
      </MolecularStateCharacterisation>
      <Case>
        <dcs:QNs>
          <dcs:ElecStateLabel>X</dcs:ElecStateLabel>
          <dcs:v>0</dcs:v>
          <dcs:J>1</dcs:J>
          <dcs:F nuclearSpinRef="C-13">0.5</dcs:F>
        </dcs:QNs>
      </Case>
    </MolecularState>

  </Molecule>
\end{verbatim}
} % \footnotesize

\linedb\ uses the {\tt OrdinaryStructuralFormula} as the species name,
but its {\tt InChIKey} is used for database queries. The partition
function is taken from the {\tt PartitionFunction} block. It can
provide any number of temperatures, it can also be absent. Each energy
level of the molecule (energy, quantum numbers, statistical weight) is
described in a separated {\tt <MolecularState>} block.

\subsubsection{Radiative transition description}

A single transition is described in the {\tt <Processes><Radiative>}
table as a {\tt <RadiativeTransition>} block. For example (truncated
for clarity):

{\footnotesize
\begin{verbatim}
  <RadiativeTransition id="PCDMS-R7452690" process="excitation">
    <EnergyWavelength>
      <Frequency methodRef="MCDMS-6648">
        <SourceRef>BCDMS-344</SourceRef>
        <Value units="MHz">104711.4035</Value>
        <Accuracy>0.0057</Accuracy>
      </Frequency>
      <Frequency methodRef="MCDMS-6646">
        <Value units="MHz">104711.3656</Value>
        <Accuracy>0.0003</Accuracy>
      </Frequency>
    </EnergyWavelength>
    <UpperStateRef>SCDMS-9240239</UpperStateRef>
    <LowerStateRef>SCDMS-9240238</LowerStateRef>
    <SpeciesRef>XCDMS-132</SpeciesRef>
    <Probability>
      <TransitionProbabilityA>
        <Value units="1/cm">5.45485286998e-08</Value>
      </TransitionProbabilityA>
    </Probability>
  </RadiativeTransition>
\end{verbatim}
} % \footnotesize

Note that the species ({\tt SpeciesRef}), the lower level ({\tt
  LowerStateRef}), and the upper level ({\tt UpperState\-Ref}) are
identified by their unique identifiers which backpoint to the given
species in the {\tt <Molecules>} table. The measured frequency is
described in a {\tt <Frequency>} block. There can be several
frequencies for a single transition, measured by several sources.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage

\section{LINEDB Language Internal Help}
\input{sic-help-linedb}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\appendix
\section{JPL convention}

The JPL convention, as of March 24th 2014, is reproduced here. This is
the expected format for ASCII local databases supported by
\linedb{}. See the online version of the document at:
http://spec.jpl.nasa.gov/ftp/pub/catalog/README
\label{app:jpl}
\begin{verbatim}
The catalog data files are composed of 80-character card images, with one card 
image per spectral line.  The format of each card image is:
  FREQ, ERR, LGINT, DR,  ELO, GUP, TAG, QNFMT,  QN',  QN" 
(F13.4,F8.4, F8.4,  I2,F10.4,  I3,  I7,    I4,  6I2,  6I2)

FREQ:  Frequency of the line in MHz.
ERR:   Estimated or experimental error of FREQ in MHz.
LGINT: Base 10 logarithm of the integrated intensity in units of nm^2 MHz at 
       300 K. 
DR:    Degrees of freedom in the rotational partition function (0 for atoms, 
       2 for linear molecules, and 3 for nonlinear molecules).
ELO:   Lower state energy in cm^{-1} relative to the ground state.
GUP:   Upper state degeneracy.
TAG:   Species tag or molecular identifier. 
       A negative value flags that the line frequency has 
       been measured in the laboratory.  The absolute value of TAG is then the 
       species tag and ERR is the reported experimental error.  The three most 
       significant digits of the species tag are coded as the mass number of 
       the species.
QNFMT: Identifies the format of the quantum numbers 
QN':   Quantum numbers for the upper state. 
QN":   Quantum numbers for the lower state. 

The on-line version of the catalog contains individual files for each
molecular species.  Line files are designated as ctttttt.cat, where tttttt 
is the zero-filled catalog tag number. For example,
the H atom line list is in file c001001.cat. 

A directory of the catalog is found in a file called 'catdir.cat.'
Each element of this directory is an 80-character record with the following 
format:
TAG,  NAME, NLINE,  QLOG,  VER 
(I6,X, A13,    I6, 7F7.4,  I2)

TAG:   The species tag or molecular identifier.
NAME:  An ASCII name for the species.
NLINE: The number of lines in the catalog.
QLOG:  A seven-element vector containing the base 10 logorithm of the partition
       function for temperatures of 300 K, 225 K, 150 K, 75 K, 37.5 K, 18.75 K,
       and 9.375 K, respectively.
VER:   The version of the calculation for this species in the catalog. 
       The version number is followed by * if the entry is newer than the
       last edition of the catalog.
\end{verbatim}

\newpage
\section{Coding the quantum numbers}

In the \linedb\ offline databases, as well as in JPL and ``old''
(non-VAMDC) CDMS, the quantum numbers of the lower and upper
transition levels are encoded in a character string. This appendix
describes the recipe to be used for encoding. It duplicates the pages
{\tt https://www.astro.uni-koeln.de/cdms/catalog} and {\tt
  https://www.astro.uni-koeln.de/node/475} for memory.

\subsection{Quantum numbers}

The quantum numbers are given in the following order:\\
$J$ (or $N$); $K_a$ and $K_c$ (or $\pm$; $K$); $v$; $F_1$ ... $F$\\
for the upper state followed immediately by those for the lower state
(see also below).

\begin{itemize}
\item $N$ is the total rotational angular momentum excluding electron
  and nuclear spins. For singlet molecules, $J$, the total rotational
  angular momentum including electron spin, is equal to $N$.
\item $K_a$ and $K_c$ are the projections of $N$ onto the A and C
  inertial axes, respectively. For symmetric top molecules, only $K$
  is needed (instead of $K_a$ and $K_c$) along with $+$ or $-$, which
  designate the parity; if redundant, the latter might be
  omitted. Instead of $K$, $\Lambda$ or $l$ may be used for linear
  molecules.
\item $v$ is a \emph{state number}! It specifies different vibrational
  or electronic states. It may also be used to distinguish between
  different species that have been fit simultaneously. Details on the
  meaning of the state numbers are given in the documentation! Note:
  More than one state number may be needed to designate one
  vibrational state - this is the case, for example, for a degenerate
  (e.g. bending) state of a symmetric top molecule!
\item $F_1$ ... $F$ designate spin quanta. In general, the electron
  spin $S$ is coupled to the rotational angular momentum first, followed
  by nuclear spins. In this case $F_1$ = $J$
\end{itemize}

Very Important:

Exactly two characters are available for each quantum
number. Therefore, half integer quanta are rounded up! In addition,
capital letters are used to indicate quantum numbers larger than
99. E.g. A0 is 100, Z9 is 359. Small types are used to signal
corresponding negative quantum numbers.

Since the program was written for asymmetric top molecules, some of
the quantum numbers may be redundant.

Six quantum numbers are available at most to describe the upper and
lower state, respectively. In case more quantum numbers are needed,
even if some of them are redundant, the only spin designating quantum
numbers are $n$, $F$, were $n$ is an aggregate spin number (see
below).

\subsection{Aggregate spin number}

The aggregate spin number is used in the SPFIT and SPCAT programs
whenever more than six quantum numbers are needed to descibe a state -
even if some of the quantum numbers are redundant. It can be decoded
using information provided in the .fit file or the .out file after the
list of parameters in both cases. The NH2 example is used, in which $S
= 1/2$, $I_N = 1$, and $I_H = 1/2$ for both H nuclei and $N + S = J$;
$J + I_N = F_1$; $I_{H1} + I_{H2} = I_{tot}$; and $F_1 + I_{tot} = F$.\\

Please note: The coding will be the same for equivalent spin
combinations, meaning one spin of 1/2, one spin of 1, and two
equivalent spins of 1/2. The coding will be different for other spin
combinations, e.g. two spins of 1/2 and two equivalent spins of 1/2
with PH2 as an example or one spin of 1, one spin of 1/2 and two
equivalent spins of 1/2 with 13CH2 as an example.

\begin{verbatim}
BLOCK - WT - SYM - V - TSP - N  -  other quanta  (rel. to F=0 )
    1    1    0    0    0  -2.5  -2.0  -1.0   1.0
\end{verbatim}

TSP is the aggregate spin number, here 0. Subsequently, $N$ and the
other quanta ($J$, $F_1$, and $I_{tot}$) are given relative to $F =
0$.

If we take, for example, line number 12:
\begin{verbatim}
  3  3  1  0  0  6  4  1  3  0  0  7   11686.80
\end{verbatim}
we see that for the upper state we have $N = 3$, hence $F = 3 + 2.5 =
6 – 0.5 = 5.5$, $J = 3.5$, $F_1 = 4.5$, and finally $I_{tot} = 1.0$ is
redundant. Similarly for the upper state: $N = 4$, hence $F = 6.5$, $J
= 4.5$, $F_1 = 5.5$, and finally $I_{tot} = 1.0$ is again redundant.
For TSP = 1 we find:
\begin{verbatim}
    2    1    1    0    1  -1.5  -1.0   0.0   0.0
\end{verbatim}
For example in line 21 there is TSP = 1 twice:
\begin{verbatim}
  5  2  3  0  1  7  6  1  6  0  1  8    8749.68
\end{verbatim}

For the upper and lower state, respectively:\\
$N = 5$, $N = 5.5$, $F_1 = 6.5$, $I_{tot} = 0.0$, and $F = 6.5$.\\
$N = 6$, $N = 6.5$, $F_1 = 7.5$, $I_{tot} = 0.0$, and $F = 7.5$.

\newpage
\section{CDMS Species}
\label{app:species}

List of the 734 CDMS species and their InChI as of 2016, February
24th.

\footnotesize
\include{cdms-vamdc-species}

\end{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
