.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
.ti +10
LINEDB_\ Command Language Summary
.br
This language is an interface to on-line and off-line line catalogs.

.nf
USE       Define the atomic and molecular line database(s) used as input and/or output
SELECT    Select lines in the input database(s) according to user defined filters
LIST      List lines from the current line index
INSERT    Insert lines from the current line index into the output database
REMOVE    Remove lines from the current line index from the output database
.fi
.\"====================================================================
.ti -4
1 USE
.ti +4
LINEDB_\USE IN|OUT|BOTH dbname1 [[dbname2]  [dbname3...]] [/ASTRO]
[/OVERWRITE]

Define the atomic and molecular line database(s) used as input and/or
output. 

Input databases can be either an existing filenames or a database available
through internet. Recognized internet databases are
.nf
   JPL    the JPL molecular spectroscopy database
   CDMS   the Cologne Database for Molecular Spectrocopy
.fi
These names can thus not be used as database filenames. 

The input file is tested to determine whether it is a valid SQLITE
database. If not, it is assumed to be an ASCII file following the JPL data
format, see e.g.
.ti +4
https://spec.jpl.nasa.gov/ftp/pub/catalog/README, and
.ti +4
https://spec.jpl.nasa.gov/ftp/pub/catalog/catdir.html
.br
for reference and examples. In this case, the log10 of the partition
functions of all the referenced species must be provided in a file
named "partfunc.cat", with at least the 300K value. See
kernel/python/linedb/demo/demo-53001.cat and
kernel/python/linedb/demo/partfunc.cat in the Gildas sources for a
complete example.

Multiple input databases can be used together. However, only one output
database can be defined at a given time. The OUT and BOTH keywords applies
only to SQLITE databases. The /OVERWRITE option implies that the output
database is first removed. The absence of the option implies that any
subsequent call to the INSERT command will append lines to the already
existing output database.

After execution of the command, the name of the input databases is
saved in the list LINEDB%DBIN. For symmetry, the name of the output
database is saved in the list LINEDB%DBOUT (with a single element in
this case).
.\"--------------------------------------------------------------------
.ti -4
2 /ASTRO
.ti +4
[LINEDB_\]USE OUT dbname /ASTRO [/OVERWRITE]

Create an output catalog using the Astro format, i.e. an ASCII table
with frequencies (GHz) in first column and species name in second
column, plus possibly comment lines and trailing comments.

This output kind can only be used to export (USE OUT + INSERT) lines.
USE IN is forbidden.

When INSERT is invoked several times (in the same session, or when
reopening an output catalog), it does NOT CHECK FOR DUPLICATES. REMOVE
is not available.
.\"====================================================================
.ti -4
1 SELECT
.ti +4
LINEDB_\SELECT [/ORIGIN Originname] [/SPECIES Name1 Name2 ...] [/FREQ
Fmin Fmax] [/ENERGY Emax] [/AIJ Amin] [/SORTBY Order] [/EPSILON Eps]

Select lines available from the input database. An index containing
the line information is formed and a SIC structure mapping these
information is defined.

The index can be sorted by increasing frequency or energy. One or more
species name can be provided. In offline catalogs, the search is
case-insensitive and wildcards '*' can be used, while online catalogs
do not implement this possibility. A possible workaround of this
limitation is to make a local copy of an online database (with all
filters enabled except species name) and search in it:
.nf
  SIC> use in cdms
  SIC> select /freq 123000 124000
  SIC> use out tmp.db
  SIC> insert
  SIC> use in tmp.db
  SIC> select /spec ch3o*
.fi

The initial origin of the line (e.g. JPL, CDMS or private catalog),
the name of the species, a frequency range, the maximum energy of the
upper level and the maximum Einstein coefficient Amin can be used as
filters in the line selection process. By default, Amin defaults to
1e-10, i.e. lines with a smaller Einstein coefficient are filtered
out.

As an output, the LINES SIC structure will contain the content of the
current index, i.e.,
.nf
   LINES%          Global structure       
   LINES%N         Integer scalar      [---] Number of lines in current index
   LINES%SPECIES   Character[LINES%N]  [---] Species names
   LINES%FREQUENCY Double[LINES%N]     [MHz] Frequencies
   LINES%UNCERTAINTY Real[LINES%N]     [MHz] Uncertainty of the line frequency
   LINES%AIJ       Double[LINES%N]     [s-1] Einstein coefficient
   LINES%EUP       Real[LINES%N]       [  K] Upper level energy
   LINES%GUP       Real[LINES%N]       [---] Upper level degeneracy
   LINES%QNUP      Character[LINES%N]  [---] Upper level quantum numbers
   LINES%ELOW      Real[LINES%N]       [  K] Lower level energy	  
   LINES%GLOW      Real[LINES%N]       [---] Lower level degeneracy
   LINES%QNLOW     Character[LINES%N]  [---] Lower level quantum numbers
.fi

The lines will be sorted according to Order, which can be any
combination of "frequency", "energy" and "aij", and all the
subsequent permutations.  Default is frequency. If sortby is
["energy", "aij"] and if epsilon is specified, aij will be
used as a criterion when the difference in energy is less than
epsilon.
.\"====================================================================
.ti -4
1 LIST
.ti +4
LINEDB_\LIST [/FULL] [/TOC]

List a set of columns for all lines found in the current index built
during the last SELECT command. The option /FULL lists all the columns
available in the database.

The /TOC option partitions the lines by equivalence class (species
name) and gives a count of each class.
.\"====================================================================
.ti -4
1 INSERT
.ti +4
LINEDB_\INSERT

Insert the entries (lines properties and partition functions) of the
current line index (result of the last SELECT command) into the output
database.
.\"====================================================================
.ti -4
1 REMOVE
.ti +4
LINEDB_\REMOVE

Remove the entries (lines properties and partition functions) of the
current line index (result of the last SELECT command) into the output
database. The partition function is erased only if no other line of the
same species remains in the database.
.\"====================================================================
.ti -4
1 ENDOFHELP
