-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathSLAP2.tex
More file actions
1464 lines (1099 loc) · 63.9 KB
/
SLAP2.tex
File metadata and controls
1464 lines (1099 loc) · 63.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[11pt,a4paper]{ivoa}
\input tthdefs
\setlength {\marginparwidth }{4cm}
\usepackage{todonotes}
\usepackage{supertabular}
\usepackage{float}
\usepackage{tabularx}
\usepackage{enumitem}
\usepackage{url}
\lstset{flexiblecolumns=true,showstringspaces=False,
language={},breaklines=true,breakatwhitespace=true}
\newcommand{\parexample}[1]{\noindent\quad\texttt{#1}}
\title{Simple Line Access Protocol}
\ivoagroup{Data Access Layer}
\author{Moreau, N.}
\author{Salgado, J.}
\author{Osuna, P.}
\author{Demleitner, M.}
\author{Guainazzi, M.}
\author{Dubernet, M.-L.}
\author{Tody, D.}
\author{Zwölf, C.M.}
\editor{Moreau, N.}
\previousversion[https://ivoa.net/documents/SLAP/20101209/]{REC-1.0}
\def\ivoaDocdatecode{20250627}
\def\ivoaDocname{SLAP2}
\def\ivoaDocversion{1.0}
\def\ivoaDocdate{2025-06-17}
\def\ivoaDocauthors{Nicolas Moreau}
\def\ivoaDocstatus{WD}
\def\ivoaDocid{IVOA-SLAP2-1.0}
\def\ivoaDoctype{WD}
\begin{document}
\begin{abstract}
The Simple Line Access Protocol (SLAP) is an IVOA
\textit{{Data Access protocol}} which defines a protocol for retrieving
spectral lines coming from various \textit{{Spectral Line Data
Collections}} through a uniform interface within the VO framework.
These lines can be either observed or theoretical and will be typically
used to identify emission or absorption features in astronomical
spectra.
It makes use of the \href{https://dictionary.vamdc.eu/}{VAMDC dictionary} to define the query parameters and the returned data. This dictionary is actually the equivalent of a
relational database view built on top of the data model defined in the \textit{VAMDC XSAMS schema 12.07}
\citep{std:XSAMS12.07}. The primary objective of this schema is to set up a framework for the correct exchange of atomic, molecular and particle-surface interaction processes data. It has been developed and is currently maintained by the \href{https://vamdc.org/structure/presentation/}{VAMDC Consortium}. Each quantity defined in the dictionary is clearly defined and related to a field in the VAMDC schema.
Physical units are described by using the standard VO Units syntax \citep{2014ivoa.spec.0523D}.
SLAP services can be registered in an IVOA \textit{Registry of Resources}
where they have a unique \textit{ResourceIdentifier}
\citep{2016ivoa.spec.0523D}.
They will be described using the Simple Line Access extension
\citep{2017ivoa.spec.0530P} of VOResource to specify their
compliance level with the SLAP standard and the accepted query
parameters.
The SLAP interface is meant to be reasonably simple to implement by
service providers. A basic query will be done in a wavelength range for
the different services, using the \{lines\} resource. The service
returns a list of spectral lines formatted as a VOTable. An
implementation of the service may support additional search parameters
(some of which may be custom to that particular service) to control more finely the selection of spectral lines.
\end{abstract}
\section*{Acknowledgments}
The authors acknowledge the comments from the DAL WG members, from the
IVOA members in general and from the VAMDC Consortium members.
\section*{Conformance-related definitions}
% CHANGE FROM .DOC: this replaces the "Requirements for complicance"
% section that had some additional (but probably unused) language
The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{http://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.
\section{Introduction}
This Simple Line Access Protocol (SLAP henceforth) in its first version \citep{2010ivoa.specQ1209O} made
use of the work done in the Simple Spectral Lines Data Model definition \citep{2010ivoa.spec.1209O}, as the source of the abstract representation of
a spectral line. This second version now relies on the standardization work made by
the VAMDC Consortium in the XSAMS data model to describe quantities \citep{std:XSAMS12.07}.
Web services in the Virtual Observatory infrastructure share a common
interface, described in the Data Access Layer Interface 1.1
\citep{2017ivoa.spec.0517D}, a document describing behaviors that must be
implemented by all services concerning for example :
\begin{itemize}
\item the use of VOTable for encoding search results,
\item the mechanism for handling errors, and
\item the retrieval of service metadata.
\end{itemize}
Following these specifications, the SLAP interface is in many ways
similar to that of SSAP \citep{2012ivoa.spec.0210T} and SIAP (v2.0)
\citep{2015ivoa.spec.1223D}. However, SIAP and SSAP protocols are
two-step processes. In the first step, the VO client application
requests metadata from the server. These metadata include links to
images or spectra. In the second step, the VO client application
requests the data from the server. In the particular case of Simple Line
Access Services, a service will be, in essence, a one-step process,
i.e., only one request is needed whose result includes both data and metadata and from that point
of view it looks more like the Simple Cone Search protocol
\citep{2008ivoa.specQ0222P}.
Even if no link to astronomical products is expected because of the
nature of the service, the metadata associated to each line could contain reference
links to html pages, spectra files, spectral line profiles, etc. This is particularly useful for data citation
because when the output table contains a DOI it can be cited along the data to ensure proper credit to data provider.
\subsection{Role within the VO Architecture}
\begin{figure}[H]
\centering
\includegraphics[width=0.8\textwidth]{role_diagram.pdf}
\caption{Architecture diagram for this document}
\label{fig:archdiag}
\end{figure}
Fig.~\ref{fig:archdiag} shows the role this document plays within the
IVOA architecture \citep{ivoaArchitecture}.
\subsection{Link with VAMDC standards}
The VAMDC Consortium is a consortium of Institutes and Research Institutions that share a common technical and political framework
for the distribution and curation of atomic and molecular data. It developed a set of standards to enable the exchange
of data within its infrastructure.
Among them, the \textit{VAMDC XSAMS schema 12.07} \citep{std:XSAMS12.07} provides a structured presentation of
Atomic, Molecular, Particle and Surface Interaction data in an XML file. It is based on the physical representation of interaction
between various objects through description of the physical states and interaction characteristics.
This data model has been used to build the \href{https://dictionary.vamdc.eu/}{VAMDC dictionary}. This is a list of keywords, with their definition,
that can be used when writing queries in the VAMDC variant of the TAP protocol called
VSS2 \href{https://standards.vamdc.eu/queryLanguage/vss2.html#introduction}.
This list of keywords can be considered as a view on the VAMDC data model and avoid the need to use the FROM clause in queries.
There are different types of keywords in the dictionary that will be used in this document :
\begin{enumerate}
\item Restrictables : the criteria that can be used to filter out data in VAMDC queries
\item Returnables : the data fields that will be contained in the output
\end{enumerate}
In the SLAP2 protocol, the query parameters are mapped to VAMDC restrictables and the output fields to VAMDC returnables.
\section{Spectral line service type}
\label{sect:service-type}
It is assumed that compliant spectral line services fall into one of two categories.
\begin{enumerate}
\item Observational line databases. Lines observed and identified in
real spectra collected by different instrument/projects.
\item Theoretical line databases. Servers containing theoretical
spectral lines will be included in this group.
\end{enumerate}
In both cases, the line description and the identification might be
already present in a scientific publication, which should always be
provided when available to guarantee the provenance of data.
This document describes standard query parameters for SLAP services.
Some SLAP services might make use of extra parameters, not cited in this
document, to support additional filtering and selection.
However, the theoretical line database services could make use of extra
parameters not cited in this document to filter out lines not expected
to be identified in an observed spectrum or to score the output lines
due to the application of physical models.
Examples:
\begin{itemize}
\item For the Stark-b database \citep{2012JPhCS.397a2019S} which provides widths and shifts of isolated lines of neutral and ionized elements due to electron and ion impacts, it is necessary to provide the perturber density and the temperature to filter the transitions.
\item For the NIST Atomic Spectra Database Lines \citep{NIST_ASD}
as it is extracted from the Saha-LTE model, ``\textit{The level
populations are calculated according to the Boltzmann distribution
within each ion and Saha distribution between the ion stages. Thus, to
calculate the spectrum from a single ion, e.g., C I, only
}\textbf{T}\textbf{\textsubscript{e}}\textit{ is required, while for the
spectrum from several ions of the same element (e.g., C I-V),
}\textbf{N}\textbf{\textsubscript{e}}\textit{ must be defined as
well.}''
\end{itemize}
At the same time, for observational spectral line databases, some
project specific search parameters may be used.
Example:
In ISO Astronomical Spectroscopy Database (IASD),
the observation number parameter can be used to select only the lines
observed during this ISO satellite observation.
Since it is not the role of a standard to compile service specific parameters,
a general mechanism is described. As will be explained
later, the discovery of these extra parameters by VO client applications
or by the registry relies on an implementation of a VOSI-capabilities
endpoint \citep{2017ivoa.spec.0524G}.
\section{Use cases}
\label{sect:use-cases}
The SLAP protocol aims at covering some classic use cases, some of which
will be described below.
\subsection{Discovering the content of a database}
\label{sect:content-discovery}
In the context of a graphical user interface (be it a web interface or a
local standalone application) able to query SLAP services, an
application might need to provide the list of species available in a
service, in which the user could choose what he requires. To achieve
this, the application can send a query to the \{species\} endpoint of a
service and build a graphical list object from the content of the
returned VOTable.
By caching locally this list, one might also be able to implement an
auto-completion feature if the user wants to manually enter the name of
a species.
\subsection[Identifying a Single Line in a spectrum]{Identifying a Single Line in a spectrum}
\label{sect:line-id}
A user sees a feature in a spectrum with known (and reliable) spectral
calibration and now wants to know what might possibly be responsible for
it. Hence, they query a narrow spectral range and retrieve all known lines
from all services.
To select which of the candidate lines are plausible matches, users would
inspect line metadata such as the originating atom or molecule, the ionisation
state, oscillator strengths or quantum numbers to identify rotational or vibrational level.
\subsection{Restricting the lines search}
\label{sect:restricting-search}
\subsubsection{Finding available lines for a given species}
\label{sect:finding-all}
Using a mass spectrometer, researchers find a molecule with the sum formula C16H10 in a comet. They now want to figure out whether any line in the spectrum of the coma of the parent object corresponds to some molecule with that sum formula. Conversely, a researcher may want to find lines of Methane or perhaps even Methane with one hydrogen atom being replaced by a deuteron.
In that case, a first step could be to search in the list of available species if the \{species\} endpoint is available,
then using the \{lines\} endpoint with CHEMICAL\_ELEMENT or INCHIKEY parameters.
\subsubsection{Finding Well-Known Lines}
\label{sect:finding-known-line}
A user wants to display the Lyman series over a plot of a spectrum. Hence, a client needs to discover which service holds such data, select the appropriate records - presumably by their properties, perhaps even by their name -, and retrieve them. If multiple services hold the desired data, it might need to reconcile differing specifications.
This could be done by defining H as the searched CHEMICAL\_ELEMENT and providing a narrow WAVELENGTH interval corresponding to each lines in the serie.
\subsubsection[Retrieving Spectral Lines for Cross-Identification]{Retrieving Spectral Lines for Cross-Identification}
\label{sect:line-cross-id}
Users may have various reasons to retrieve a larger number of spectral lines:
When analysing a given spectrum, selecting spectral lines that may fit the ones in the spectrum, for instance to establish the source's chemistry or physical state. Depending on the prior knowledge of the source, they will want to constrain the matches to specific species in specific ionisation (or even excitation) states.
When estimating the redshift of an object, features found in the spectrum need to be matched to the rest wavelengths.
When computing theoretical spectra, a comparison to the (observed) ground truth is desirable.
The challenge in all these cases is that displaying all lines known obviously is impossible due to the sheer volume of the data, and it would not help users in any way. Hence, the client needs to have some idea of which lines can be expected to be strong given the physics of the emission's source region.
Selecting the lines before retrieval is a significant optimisation in this case, as in wider spectra at least hundreds of thousands of lines will be within the spectral range, while it probably rarely makes sense to plot more than a hundred or so. Hence, careful selection of lines can reduce the volume of data transferred and processed by the client by several orders of magnitude.
To make good on this promise, the service need to be queryable such that lines suspected to be strong for some combination of chemistry, temperature, and pressure can be filtered out with some accuracy.
\clearpage\section{Query interface}
\label{sect:query-interface}
The SLAP resources are synchronous web service resources that conform to
the DALI-sync description \citep{2017ivoa.spec.0517D}. For a DALI-sync
resource, the parameters for a request may be submitted using an HTTP
GET (query string) or POST action.
\subsection{Resources}
\label{sect:dali-resources}
The table below shows the list of available resources for a
service and their mandatory status.
\begin{table}[htbp]
\centering
\caption{Description of available resources}
\begin{tabular}{p{4.806cm}p{4.894cm}p{4.951cm}}
\sptablerule
\textbf{Resource type}&
\textbf{Resource name}&
\textbf{Required}\\
\sptablerule
DALI-sync &
/lines &
yes\\
DALI-sync &
/species &
yes\\
VOSI-availability &
/availability &
no\\
VOSI-capabilities &
/capabilities &
yes\\
DALI-examples &
/examples &
no\\
\sptablerule
\end{tabular}
\end{table}
In order to distinguish between resources when a service is declared in
a registry, the following standardIds will be used :
\begin{itemize}
\item \{lines\} : ivo://ivoa.net/std/SLAP\#lines-2.0
\item \{species\} : ivo://ivoa.net/std/SLAP\#species-2.0
\end{itemize}
\subsection{Input parameters}
\label{sect:input-pars}
As specified in the DALI recommendation, parameter names are not
case sensitive; a SLAP service must treat upper-, lower-, and mixed-case
parameter names as equal. Parameter values are case sensitive.
All query parameters are multi-valued which means multiple occurrences
of the parameter=value pairs as specified in the DALI recommendation are
permitted, excepting the MAXREC parameter which is single valued.
The constraints from multiple occurrences of a parameter are
combined with a logical OR operator. The constraints from different
parameters are combined with a logical AND operator. In accordance with these rules,
a query to search lines for both hydrogen and helium atoms at once can be written as follows : \\
CHEMICAL\_ELEMENT=H\&CHEMICAL\_ELEMENT=He \\
Query parameters for text or string fields are always case-sensitive and indicate an exact match. \\
Query parameters for numeric fields accept a single numeric value or a range
of values with optional lower and upper bounds. Such range values
are encoded using the VOTable array serialisation (space separated). If the
lower or upper bound is not specified, the range is open-ended. In VOTable
arrays this uses the special values -Inf or +Inf. \\
For example, the interval [300,600] is: \\
300 600 \\
The open-ended interval [300,infinity) (all values greater than or equal to
300) is: \\
300 +Inf \\
The open-ended interval (-infinity,600] (all values less than or equal to 600)
is: \\
-Inf 600 \\
The open-ended interval (-infinity,infinity) (all values) is: \\
-Inf +Inf\\
If specified, the boundary value is always included in the interval. The units
for numeric values are specified for each parameter and never included in the
value.
\section{\{lines\} resource}
\label{sect:lines-res}
The purpose of this resource is to allow users/clients to search in a
wavelength range for spectral lines. This resource MUST be implemented
by a SLAP service. The most basic query parameters will be the minimum
and maximum value for the wavelength range. Additional parameters may be
used to refine the search or to model physical scenarios.
\subsection{Parameters}
\label{sect:lines-pars}
A service must support all the input parameters described in this section.
That means that the service must accept them as valid ones without
raising an error, and the parameters must be properly used to constrain
the query.
If one or several parameters can not be implemented in the context of a service,
an error must be raised when the parameter is received in a query (see \ref{par:QUERY_STATUS} for the appropriate syntax).
\subsubsection{WAVELENGTH}
The \textbf{WAVELENGTH} parameter specifies the wavelength spectral range,
to be specified in meters. This wavelength range will be interpreted as the wavelength in the vacuum of
the transition originating the line (ucd=\ucd{em.wl}; corresponding VAMDC restrictable is {\textquotedbl}RadTransWavelength{\textquotedbl}
to be specified in Angstroms).
As the units in the spectral line database could be different than
meters, the service will need to translate from the selected units
(meters) to the internal ones. The selection of one type of units (in
this case the SI unit meters) will help to unify access to different
spectral line databases, even when in some cases, the unit selected
(meter) may not be the best one for the range on interest.
Example
To query for spectral lines in the wavelength range between 5.1 and 5.6
micrometers ( both values are included in search ):
\parexample{WAVELENGTH=5.1E-6 5.6E-6}
\subsubsection{MAXREC}
The MAXREC parameter, defined in DALI, allows the client to
limit the number of records in the response. A service implementation
may also impose default and maximum values for this limit. However the
limit is determined, if the output is truncated due to the limit, the
server must indicate this using an overflow indicator (\ref{par:QUERY_STATUS}) except in the special
case of MAXREC=0 where the service responds with metadata-only (normal
output document with no records).
This parameter is single valued and services must respond with an error if
the request includes multiple values for it.\\
Display only 100 lines:
\parexample{MAXREC=100}
\subsubsection{CHEMICAL\_ELEMENT}
The \textbf{CHEMICAL\_ELEMENT} parameter would constrain the search to
the selected chemical element. A list of different chemical elements
could be queried by specifying this parameter multiple times (ucd=\ucd{phys.atmol.element}).
Atom can be specified exactly by symbol (corresponding VAMDC restrictable is {\textquotedbl}AtomSymbol{\textquotedbl}).
Molecules can be specified by conventional molecular name (formula like CO2, CH4 or names like carbon or water {\dots})
which might not be unique (corresponding VAMDC restrictable is {\textquotedbl}MoleculeChemicalName{\textquotedbl}).
The \{species\} endpoint is the recommended place to discover the correct syntax of a given species in a particular service.
Filter results for Iron only :
\parexample{CHEMICAL\_ELEMENT=Fe}
Filter results for Carbon Dioxide molecule only:
\parexample{CHEMICAL\_ELEMENT=CO2}
\subsubsection{INCHIKEY}
InChI is an acronym for IUPAC International Chemical Identifier \citep{Heller2015}.
It is a string of characters capable of uniquely representing a chemical substance.
InChIKey is a compact chemical identifier derived from InChI. The InChIKey is always
only 27-characters long.
The \textbf{INCHIKEY} parameter (ucd=\ucd{phys.atmol.element}; corresponding VAMDC restrictable is {\textquotedbl}InchiKey{\textquotedbl})
constrains the search to the chemical element corresponding the provided inchikey value. A list of different
inchikeys could be queried by specifying this parameter multiple times.
The \{species\}
endpoint is the recommended place to discover the InChIkey of a given species in a particular service. You can also
use the dedicated \href{https://species.vamdc.org/}{VAMDC Species service}. This service relies on the VAMDC Species
Database \citep{Zwölf2024} that regularly harvest the species for which data are available within the VAMDC infrastructure.
Filter results for neutral Iron atom (InChI=1S/Fe) only :
\parexample{INCHIKEY=XEEYBQQBJWHFJM-UHFFFAOYSA-N}
\subsubsection{SPECIES\_MASS}
The \textbf{SPECIES\_MASS} parameter specifies the minimum and maximum possible mass value
for the searched species, to be specified in Unified Atomic Mass Unit (u).
The mass will be a float value greater than 0. The provided range will be interpreted as the
mass of the chemical species (ucd=\ucd{phys.atmol.element;phys.mass};
corresponding VAMDC restrictable are {\textquotedbl}AtomMass{\textquotedbl} for atoms and
{\textquotedbl}MoleculeMolecularWeight{\textquotedbl} for molecules).
Filter all atoms chemical species between 0 and 12.011 u:
\parexample{SPECIES\_MASS=0 12.011}
\subsubsection{ION\_CHARGE}
The \textbf{ION\_CHARGE} parameter specifies the minimum and maximum charge
of an ion (ucd=\ucd{phys.atmol.element;phys.atmol.ionization};
corresponding VAMDC restrictable is {\textquotedbl}IonCharge{\textquotedbl}).
It will look for the ionized forms of the chemical element specified in CHEMICAL\_ELEMENT
parameter. If it is not defined, the restriction will be applied to all
the ions available. If several CHEMICAL\_ELEMENT values have been
provided, the ion charge values will be applied to each one of them.
The charge will be an integer value greater than 0 for ionized species
(positive charge), less than 0 for negative charge (excess electrons), 0
for neutral.
All lines related to Fe+ ion:
\parexample{CHEMICAL\_ELEMENT=Fe\&ION\_CHARGE=1}
All lines related to positively charged Fe ions and excluding the neutral form :
\parexample{CHEMICAL\_ELEMENT=Fe\&ION\_CHARGE=1 +Inf}
\subsubsection{LOWER\_LEVEL\_ENERGY}
The \textbf{LOWER\_LEVEL\_ENERGY} parameter specifies the minimum and maximum energy for the LOWER level of the transition,
to be expressed in Joules (ucd=\ucd{phys.energy;phys.atmol.level}; corresponding VAMDC restrictable
is {\textquotedbl}StateEnergy{\textquotedbl}).
Energy of lower level between 3.93E-18 and 3.94E-18 Joules:
\parexample{LOWER\_LEVEL\_ENERGY=3.93E-18 3.94E-18}
\subsubsection{UPPER\_LEVEL\_ENERGY}
The \textbf{UPPER\_LEVEL\_ENERGY} parameter specifies the minimum
and maximum energy for the UPPER level of the transition, to be expressed in Joules (ucd=\ucd{phys.energy;phys.atmol.level};
corresponding VAMDC restrictable is {"StateEnergy"}).
Energy of upper level between 3.93E-18 and 3.94E-18 Joules:
\parexample{UPPER\_LEVEL\_ENERGY=3.93E-18 3.94E-18}
\subsubsection{TEMPERATURE}
The \textbf{TEMPERATURE} parameter specifies the minimum and maximum expected temperatures of the object, to
be specified in Kelvin (ucd=\ucd{phys.temperature};corresponding VAMDC restrictable
is {\textquotedbl}EnvironmentTemperature{\textquotedbl}). This parameter would be used (in particular for
theoretical spectral line databases) to sort the lines in the output
using physical models.
Temperature between 10 and 50 Kelvins:
\parexample{TEMPERATURE=10 50}
\subsubsection{EINSTEINA}
The \textbf{EINSTEINA} parameter constrains the
transition probability by specifying the minimum and maximum Einstein A, defined as the probability
per unit time s\textsuperscript{-1} for spontaneous emission in a bound-bound
transition (ucd=\ucd{phys.atmol.transProb};corresponding VAMDC restrictable
is {\textquotedbl}RadTransProbabilityA{\textquotedbl}).
Transition probability between 1.1E-7 and 1.2E-7 s-1:
\parexample{EINSTEINA=1.1E-7 1.2E-7}
\subsubsection{Custom query parameters}
As we saw in Section 3, there is a need to have a general mechanism for
free query parameters to filter out or sort the table result.
Both for the non-compulsory parameters and/or for the free ones, client
applications can discover whether a particular parameter is implemented
through the VOSI-capabilities operation.
Using this information, a VO client would be able to dynamically
construct a form, where this information could be inserted.
\subsection{Successful output}
\label{sect:lines-output}
The output returned by a SLAP service is a VOTable
\citep{2013ivoa.spec.0920O}, an XML table format, returned with a
MIME-type of {\textquotedbl}application/x-votable+xml{\textquotedbl}.
The table lists all the Spectral lines found in the server database that
match the query constraints.
It \textbf{MUST} contain a RESOURCE element identified with the tag
type={\textquotedbl}results{\textquotedbl} that \textbf{SHOULD} contain
a single TABLE element which contains the results of the query. The
VOTable is permitted to contain additional RESOURCE elements, but the
usage of any such elements is not defined here. If multiple resources
are present it is recommended that the query results be returned in the
first resource element.
The VOTable \textbf{MAY} contain references to other name spaces, like
SLAP, Characterization, etc.
\subsubsection[RESOURCE element]{RESOURCE element}
\label{sect:resource-element}
The RESOURCE element contains several INFO elements that store metadata
about the request execution and the queried service.
These metadata facilitate the identification of the data provenance and enable the reproducibility
of the query on the service.
They are originally described in the Data Origin document \citep{ivoaDataOrigin1.1},
with the exception of QUERY\_STATUS, which is described in DALI 1.1 \citep{2017ivoa.spec.0517D}.
\paragraph{QUERY\_STATUS}\label{par:QUERY_STATUS}
It \textbf{MUST} contain an INFO with
name={\textquotedbl}QUERY\_STATUS{\textquotedbl}. Its value attribute
MUST be set to {\textquotedbl}OK{\textquotedbl} if the query is executed successfully,
regardless of whether any matching spectral lines were found. \ If an
overflow occurs (result exceeds MAXREC) the value attribute will be set
to {\textquotedbl}OVERFLOW{\textquotedbl}. \\
Successful query example :
\begin{lstlisting}{language=XML}
<INFO name="QUERY_STATUS" value="OK" />
\end{lstlisting}
Error example :
\begin{lstlisting}{language=XML}
<INFO name="QUERY_STATUS" value="ERROR">Parameter TEMPERATURE is not supported</INFO>
\end{lstlisting}
\paragraph{request\_date}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}request\_date{\textquotedbl}.
\begin{lstlisting}{language=XML}
<INFO name="request_date" value="2025-10-31T14:57:18+01:00" />
\end{lstlisting}
\paragraph{request}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}request{\textquotedbl} containing the application/x-www-form-urlencoded
form of the query parameters in the query part of the URL.
\begin{lstlisting}{language=XML}
<INFO name="request" value="https://myvo.org/slap2/lines?WAVELENGTH=9e-8+9.1e-8"/>
\end{lstlisting}
\paragraph{service\_ivoid}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}service\_ivoid{\textquotedbl} containing the ivoid
of the service that executed the query.
\begin{lstlisting}{language=XML}
<INFO name="service_ivoid" value="ivo://myvo.org/slap2"/>
\end{lstlisting}
\paragraph{service\_protocol}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}service\_protocol{\textquotedbl} containing the ivoid
of the protocol.
\begin{lstlisting}{language=XML}
<INFO name="service_protocol" value="ivo://ivoa.net/std/SLAP#lines-2.0"/>
\end{lstlisting}
\paragraph{publisher}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}publisher{\textquotedbl}.
\begin{lstlisting}{language=XML}
<INFO name="publisher" value="Data center name"/>
\end{lstlisting}
\paragraph{last\_update\_date}
The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}last\_update\_date{\textquotedbl}.
\begin{lstlisting}{language=XML}
<INFO name="last_update_date" value="2025-09-20T12:00:00+01:00"/>
\end{lstlisting}
\subsubsection{The TABLE element}
Each table row represents a different spectral line.
Suggested UCDs are given for every columns but services are allowed to use other UCDs if more appropriate.
\subsection{Standard output fields}
\subsubsection{vacuum\_wavelength}
Exactly one field \textbf{MUST} have name={"vacuum\_wavelength"},
with datatype={"double"}, unit={"m"} and
ucd=\ucd{"em.wl"}, containing the wavelength in
vacuum of the transition originating the line in meters.
The corresponding VAMDC returnable is {"\textbf{RadTransWavelength"}}.
The NULL value is not authorized.
\subsubsection{vacuum\_wavelength\_original}
At most one field \textbf{MAY} have name={"vacuum\_wavelength\_original"},
with datatype={"double"} and ucd=\ucd{"em.wl"}. If present, this field will contain the wavelength in vacuum
of the transition originating the line, expressed in the original unit used in the source database
(if the value was not originally provided in meters).
The content of the unit attribute specifies the original unit in accordance with
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.
The corresponding VAMDC returnable is {"\textbf{RadTransWavelength"}}.
\subsubsection{vacuum\_wavelength\_error}
Exactly one field \textbf{MUST} have name={"vacuum\_wavelength\_error"},
with datatype={"double"}, unit={"m"} and
ucd=\ucd{"em.wl"}, containing the total error for the wavelength in
vacuum of the transition originating the line in meters.
The corresponding VAMDC returnable is {"\textbf{RadTransWavelengthAccuracy"}}.
The NULL value is authorized if the value is unknown.
\subsubsection{vacuum\_wavelength\_error\_original}
Exactly one field \textbf{MAY} have name={"vacuum\_wavelength\_error\_original"},
with datatype={"double"} and ucd=\ucd{"em.wl"}, containing the total error for the wavelength in
vacuum of the transition originating the line. The unit specified in the unit attribute must be
identical to the one used in the \textbf{vacuum\_wavelength\_original} field.
The corresponding VAMDC returnable is {"\textbf{RadTransWavelengthAccuracy"}}.
\subsubsection{line\_title}
Exactly one field \textbf{MUST} have name={"line\_title"}, with
datatype={"char"}, arraysize={"*"} and ucd=\ucd{"meta.title"}, containing a small description identifying the line.
The corresponding VAMDC returnable is {"\textbf{RadTransComment}"}.
Note that this line title is only a short string representation to be
used in the clients for display. There is no required syntax, but it is
recommended that common species and transition notation be used when
applicable. The NULL value is not authorized.
Examples:
\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
\item \verb|H I|
\item \verb|N III 992.873 A|
\item \verb|H2 0-0 S(1)|
\item \verb|H2 v=1, J=2 -> v=0, J=0|
\end{itemize}
In case of corrected but unidentified lines, some examples could be:
Examples: \verb|M31 1001.784 A|, \verb|011910191 800.2 A|
\subsubsection{chemical\_element\_name}
Exactly one field \textbf{MUST} have
name={"chemical\_element\_name"}, with datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}.
In the case of an atom, the corresponding VAMDC returnable is {"\textbf{AtomSymbol}"}.
If this is a molecular line, the corresponding VAMDC returnable is {"\textbf{MoleculeChemicalName}"}.\\
Example of valid values are : Fe for a iron line or CH4 for a methane line.
The NULL value is not authorized.
\subsubsection{chemical\_element\_mass}
At most one field \textbf{MAY} have name={"chemical\_element\_mass"}, with datatype={"float"} and ucd=\ucd{"phys.atmol.element"}.
The field contains the atom mass or the molecular weight of the species, to be specified in Unified Atomic Mass Unit (u).
For an atom, the corresponding VAMDC returnable is {"\textbf{AtomMass}"}.
If this is a molecular line, the corresponding VAMDC returnable is {"\textbf{MoleculeMolecularWeight}"}.
\subsubsection{inchikey}
Exactly one field \textbf{MUST} have name={"inchikey"}, with datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the inchikey \citep{Heller2015} of
the chemical element of this line. For an atom, the corresponding VAMDC returnable is {"\textbf{{AtomInchiKey}}"}
and {"\textbf{{MoleculeInchiKey}}"} for a molecular line.
The NULL value is not authorized.
\subsubsection{inchi}
Exactly one field \textbf{MUST} have name={"inchi"}, with
datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the inchi of the
chemical element of this line. The corresponding VAMDC returnable is {"\textbf{{AtomInchi}}"}
for an atomic line and {"\textbf{{MoleculeInchi}}"} for a molecular line.
The NULL value is not authorized.
\subsubsection{ion\_charge}
Exactly one field \textbf{MUST} have name={"ion\_charge"}, with
datatype={"int"} and ucd=\ucd{"phys.atmol.element;phys.atmol.ionization"}, containing the charge of the chemical element origin of the line.
The corresponding VAMDC returnable is {"\textbf{AtomIonCharge}"} for an atomic line and {"\textbf{{MoleculeIonCharge}}"} for a molecular line. The NULL value is not authorized.
\subsubsection{lower\_level\_description}
Exactly one field \textbf{MUST} have name={"lower\_level\_description"}, with datatype={"char"}, arraysize={"*"}
and ucd=\ucd{"meta.title;phys.atmol.level"}, containing a full description of the lower level of the transition originating the line.
The corresponding VAMDC returnable is {"\textbf{AtomStateDescription}"} for an atomic state and {"\textbf{MoleculeStateDescription}"} for a molecular state.
The NULL value is authorized.
Examples:
\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
\item \verb|H2 v=0, J=0|
\end{itemize}
\subsubsection{upper\_level\_description}
Exactly one field \textbf{MUST} have name={"upper\_level\_description"}, with datatype={"char"}, arraysize={"*"}
and ucd=\ucd{"meta.title;phys.atmol.level"}, containing a full description of the upper level of the transition originating the line.
The corresponding VAMDC returnable is {"\textbf{AtomStateDescription}"} for an atomic state and {"\textbf{MoleculeStateDescription}"} for a molecular state.
The NULL value is authorized.
\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
\item \verb|H2 v=1, J=2|
\end{itemize}
\subsubsection{observed\_wavelength}
At most one field \textbf{MAY} have name={"observed\_wavelength"}, with
datatype={"double"}, unit={"m"} and ucd=\ucd{"em.wl"}, containing the observed wavelength in the vacuum of
the transition originating the line in meters, as it was observed.
This may be used by observational spectral line databases.
The corresponding VAMDC returnable is {"\textbf{RadTransWavelength}"}.
\subsubsection{einstein\_a}
At most one field \textbf{MAY} have name={"einstein\_a"}, with
datatype={"double"}, unit={"1/s"} and ucd=\ucd{"phys.atmol.transProb"}, containing Einstein A value,
defined as the probability per unit time s\textsuperscript{-1} for spontaneous emission in a bound-bound transition.
The corresponding VAMDC returnable is {"\textbf{RadTransProbabilityA}"}.
\subsubsection{process}
At most one field \textbf{MAY} have name={"process"}, with
datatype={"char"} and arraysize={"*"}
describing the process for the considered transition.
Possible values are excitation or deexcitation.
The corresponding VAMDC returnable is {"\textbf{RadTransProcess}"}.
\subsubsection{lower\_level\_energy}
At most one field \textbf{MAY} have name={"lower\_level\_energy"}, with
datatype={"double"}, unit={"J"} and ucd=\ucd{"phys.energy;phys.atmol.level"}
describing the energy for the lower level of the transition which originates this line.
The value must appear in Joules to unify results.
The corresponding VAMDC returnable is {"\textbf{StateEnergy}"}.
\subsubsection{lower\_level\_energy\_original}
At most one field \textbf{MAY} have name={"lower\_level\_energy\_original"}, with
datatype={"double"} and ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the lower level of the transition which originates this line.
If present, this field will contain the energy for the lower level of the transition which originates this line,
expressed in the original unit used in the source database
(if the value was not originally provided in Joules).
The content of the unit attribute specifies the original unit in accordance with
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.
The corresponding VAMDC returnable is {"\textbf{StateEnergy}"}.
\subsubsection{upper\_level\_energy}
At most one field \textbf{MAY} have name={"upper\_level\_energy"}, with
datatype={"double"}, unit={"J"} and
ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the upper level of the transition which originates this line.
The value must appear in Joules to unify results. The corresponding VAMDC returnable is {"\textbf{StateEnergy}"}
\subsubsection{upper\_level\_energy\_original}
At most one field \textbf{MAY} have name={"upper\_level\_energy\_original"}, with
datatype={"double"} and ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the upper level of the transition which originates this line.
If present, this field will contain the energy for the upper level of the transition which originates this line,
expressed in the original unit used in the source database
(if the value was not originally provided in Joules).
The content of the unit attribute specifies the original unit in accordance with
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.
The corresponding VAMDC returnable is {"\textbf{StateEnergy}"}.
\subsubsection{transition}
At most one field \textbf{MAY} have name={"transition"}, with
datatype={"char"}, arraysize={"*"} and ucd=\ucd{"phys.atmol.transition"}.
If present, this field will contain a human readable description of the transition in terms of electron configurations
and/or quantum states before and after. A syntax suggestion is provided in the following paragraphs.
As this is a protocol meant to stay simple, the text representation is voluntarily simplified. The user
is encouraged to use the VAMDC infrastructure to get a more detailed and standardized description of the levels.
\paragraph{Atomic configuration}
It is recommended to use a LaTeX-styled \citep{lamport86latex} convention to describe sub-indexes,
super-indexes, greek characters, etc. That means the previous atomic
configuration could be serialized as string in the SLAP response in the
following way:
$$\hbox{3d\textasciicircum6 4s\textasciicircum2}$$
In the case of molecular levels, we usually need to use Greek symbols,
so, e.g.,
$$
\textrm{\textsuperscript{2}}\textrm{\textit{\textsuperscript{S}}}\textrm{\textsuperscript{
+ 1}}\textrm{$\Lambda $}\textrm{\textsubscript{$\Omega
$}}\textrm{ }
$$
would be serialized as
$$\hbox{\^\{2S+1\}{\textbackslash}Lambda \_\{{\textbackslash}Omega \}}$$
See \citep{lamport86latex} for a complete reference.
\paragraph{Molecular level quantum states}
The recommended syntax for the quantum numbers is name:numerator:denominator. Quantum Numbers are separated by the ``;'' character.
To allow for levels needing more than one quantum state to be described, the quantum states would be enclosed by square brackets.
Example: [J:1:1;F1:0:1;F:1:1]
\subsubsection{reference\_doi}
One or more fields \textbf{SHOULD} have name={"reference\_doi"}, with ucd=\ucd{"meta.ref.doi"}, datatype={"char"} and
arraysize={"*"}, to specify a digital object identifier
attached to this reference. The corresponding VAMDC returnable is {"\textbf{SourceDOI}"}.
\subsubsection{reference\_uri}
One or more fields \textbf{SHOULD} have name={"reference\_uri"},
with ucd=\ucd{"meta.ref.uri"}, datatype={"char"} and
arraysize={"*"}, to specify an http link that contains a scientific publication related to the spectral line. Since the URL will often contain metacharacters, the URL is normally enclosed in an XML CDATA section ({\textless}![CDATA[...]]{\textgreater}) or otherwise encoded to escape any embedded metacharacters. The corresponding VAMDC returnable is {"\textbf{SourceURI}"}.
\subsubsection{reference\_additional\_uri}
One or more fields \textbf{MAY} have name={"reference\_additional\_uri"} with ucd=\ucd{"meta.ref.uri"}, datatype={"char"}, arraysize={"*"} and free names, to specify URLs that contains extra information related to the spectral line. Same criteria than before about the CDATA section.
The corresponding VAMDC returnable is {"\textbf{SourceURI}"}.
\subsection{Non-standard output fields}
\label{sect:lines-nonstd}
In many occasions, extra scientifically interesting parameters may be
added to the output. Implementers are encouraged to add descriptions and
UCDs to the return fields to clarify the meaning of this information
whenever possible.
\section{\{species\} resource}
\label{sect:species}
A simple spectral service \textbf{MUST} support a resource listing all
the species for which lines are available. This operation returns the
complete list of the chemical elements available in the service. The
output returned by the service is a VOTable, an XML table format,
returned with a MIME-type of
{"application/x-votable+xml"}.
Several restriction parameters are defined to perform some
search operations on the species list. If none of those parameter is used
in the user query, the complete list of species will be returned.
A service must support all the input parameters described in this section.
That means that the service must accept them as valid ones without raising an error,
and the parameters must be properly used to constrain the query.
If one or several parameters can not be implemented in the context of a service,
an error must be raised when the parameter is received in a query
(see \ref{par:QUERY_STATUS} for the appropriate syntax).
\subsection{Parameters}
\label{sect:species-optional-parameters}
\subsubsection{ELEMENT\_TYPE}
The \textbf{ELEMENT\_TYPE} parameter specifies the type of chemical elements expected in the response.
The possible values are {"atom"} and {"molecule"}.
If the parameter is not used in the query then both atoms and molecules are returned.
Returns all the molecules :
\parexample{ELEMENT\_TYPE=molecule}
\subsubsection{INCHIKEY}
The \textbf{INCHIKEY} parameter tests the existence of a given
inchikey in the service data among the data shared by the service.
Returns the molecular hydrogen :
\parexample{INCHIKEY=UFHFLCQGNIYNRP-UHFFFAOYSA-N}
\subsubsection{NUMBER\_OF\_ATOMS}
The \textbf{NUMBER\_OF\_ATOMS} parameter specifies the number of atoms in the returned species.
There is no equivalent VAMDC restrictable for this parameter.
Di-atomic molecules: