Lines

  1"""
  2
  3This file will showcase how you can load line data from arts-cat-data into the
  4workspace and do the required setups to perform a simple forward calculations
  5using this data
  6
  7"""
  8
  9import pyarts
 10import numpy as np
 11import matplotlib.pyplot as plt
 12
 13# Initialize ARTS
 14ws = pyarts.workspace.Workspace()
 15
 16"""
 17
 18Download ARTS catalogs if they are not already present.
 19
 20"""
 21pyarts.cat.download.retrieve()
 22
 23"""
 24
 25Set ws.abs_species to the species tags that you wish to use.  Pure line-by-line
 26calculations sets the species by an expanded form of the AFGL tag system in
 27ARTS.  This example sets the isotopologue to O16-O16, "O2-66", to include all
 28lines of said isotopologue into the absorption species tag list
 29
 30There are many ways to customize this tag.  The following things are examples
 31of what is possible:
 321) Change "O2-66" to "O2".  Consequence: Not just the O2-66 isotopologue is
 33    included in the absorption species tag list but all molecular oxygen lines
 34    are included.  Note that "O2-*" is the same thing as "O2".
 352) Change "O2-66" into "O2-66,O2-68".  Consequence: Not just O2-66 but also
 36    the O16-O18 isotopologue is included as the first species tag.
 37    Note that for forward calculation purposes, writing ["O2-66,O2-68"] or
 38    ["O2-66", "O2-68"] includes the same lines but changes the layout of
 39    ws.abs_lines_per_species
 403) Change "O2-66" into "O2-66-40e9-120e9".  Consequence:  Still only the O2-66
 41    isotopologue is considered, but all lines below 40 GHz and all lines above
 42    120 GHz are considered part of another species tag.  Note that you can
 43    write your list as ["O2-66-40e9-120e9,O2-66"] to still include all lines,
 44    though this would in this particular example be a trivial waste of time
 454) Change "O2-66" to "O2-Z-66".  Consequence:  You will activate Zeeman effect
 46    calculations for O2-66.  Warning: Zeeman effect calculations are slow
 47    because they require several times more calls to core line-by-line
 48    functions.  Note that one way to speed up these calculations is to combine
 49    the tags with one of the examples above.  If you write your list of species
 50    tags as ["O2-Z-66-110e9-120e9", "O2-66"], only absorption lines between
 51    110 and 120 GHz will be treated as Zeeman-affected, but the rest of the
 52    lines are still included in the calculations.
 535) Change ["O2-66"] to ["O2-66", "H2O-161"].  Consequence: The water
 54    isotopologue H1-O16-H1 is added to your list of line-by-line absorption
 55    species.  Note that you can add as many species as you wish.  Also note
 56    that you are not allowed to write "O2-66,H2O-161" but must separate this
 57    as written at the top of this listitem.
 585) Change ["O2-66"] to ["O2-66", "O2"].  Consequence: All oxygen lines are
 59    in your list of line-by-line absorption species.  Note that you can
 60    add as many species as you wish.  Also note that you are allowed to
 61    write "O2-66,O2".
 62
 63"""
 64ws.abs_speciesSet(species=["O2-66"])
 65
 66"""
 67
 68Load the line data of the absorption tags defined in ws.abs_species into the
 69ARTS line catalog at ws.abs_lines_per_species
 70
 71The line data file is expected to be named as a line-by-line species tag.  So
 72for our species tag of "O2-66" above, the reading routine will look for the file
 73name "lines/O2-66.xml".  The search paths for these files prefer paths relative
 74to the current working directory above this available elsewhere on the system.
 75However, "lines/O2-66.xml" does exist in a fully up-to-date version of
 76arts-cat-data (if you ARTS version is recent enough) so it is likely that this
 77is the file that is selected for reading.
 78
 79The resulting ws.abs_lines_per_species will have outer size 1,
 80len(ws.abs_lines_per_species.value) == 1, after running this file as provided
 81because the size and shape of ws.abs_species is linked to the size and shape
 82of ws.abs_lines_per_species.
 83
 84If you change your tags following one of the examples above, the following
 85are the consequences:
 861) Change "O2-66" to "O2".  ws.abs_lines_per_species will now contain not just
 87    O2-66 lines but also other isotopologues.  The len of
 88    ws.abs_lines_per_species will not change.
 892) Change "O2-66" into "O2-66,O2-68".  ws.abs_lines_per_species will now
 90    contain not just O2-66 lines but also lines of O2-68.  If written as
 91    ["O2-66,O2-68"] the len of ws.abs_lines_per_species will not change.  If
 92    written as ["O2-66", "O2-68"] the len of ws.abs_lines_per_species is now 2.
 933) Change "O2-66" into "O2-66-40e9-120e9".  This will simply limit the number
 94    of lines in the line catalog.
 954) Change "O2-66" to "O2-Z-66".  The line catalog will look exactly the same
 96    but the calculations inside will change significantly
 975) Change ["O2-66"] to ["O2-66", "H2O-161"].  The len of
 98    ws.abs_lines_per_species is now 2 as the first entry are lines of O2-66 and
 99    the second entry are lines of H2O-161
1006) Change ["O2-66"] to ["O2-66", "O2"].  The len of
101    ws.abs_lines_per_species is now 2 as the first entry are lines of O2-66 and
102    the second entry are all other lines of O2.  Note therefore that ["O2", "O2-66"]
103    also has the len 2, but that all lines are now in the first entry.
104
105"""
106ws.abs_lines_per_speciesReadSpeciesSplitCatalog(basename="lines/")
107
108"""
109
110With abs_species and abs_lines_per_species both defined, you can (and must)
111confirm that the input is proper by setting lbl_checked to 1.  This is safely
112done using:
113
114"""
115ws.lbl_checkedCalc()
116
117"""
118
119You should generally always call this after you are done setting up your
120ws.abs_species and ws.abs_lines_per_species.  It will deal with the internal
121ARTS setup for you.  Note that the flag use_abs_lookup=1 can be passed to this
122method call to set up the agenda for USING the the lookup-table.  Without the
123flag, ARTS should be configured correctly either 1) to compute the lookup-table,
124or to 2) compute the absorption on-the-fly
125
126"""
127ws.propmat_clearsky_agendaAuto()
128
129"""
130
131Compute absorption
132
133Now we can use the propmat_clearsky_agenda to compute the absorption of O2-66.
134We can also use this agenda in more complicated setups that might require
135absorption calculations, but that is for other examples
136
137To just execute the agenda we need to still define its both its inputs and the
138inputs required to initialize the propagation matrix
139
140"""
141
142ws.jacobian_quantities = []  # No derivatives
143ws.select_abs_species = []  # All species
144ws.f_grid = np.linspace(40e9, 120e9, 1001)  # Frequencies between 40 and 120 GHz
145ws.rtp_mag = []  # No magnetic field
146ws.rtp_los = []  # No particular LOS
147ws.rtp_pressure = 1e5  # At 1 bar
148ws.rtp_temperature = 295  # At room temperature
149ws.rtp_nlte = pyarts.arts.EnergyLevelMap()  # No NLTE
150ws.rtp_vmr = [0.21]  # At 21% atmospheric Oxygen
151ws.stokes_dim = 1  # Unpolarized
152
153# Call the agenda with inputs above
154ws.AgendaExecute(a=ws.propmat_clearsky_agenda)
155
156# Plot the absorption of this example
157plt.figure(1)
158plt.clf()
159plt.semilogy(ws.f_grid.value / 1e9, ws.propmat_clearsky.value.data.flatten())
160plt.xlabel("Frequency [GHz]")
161plt.ylabel("Absorption [1/m]")
162plt.title("O2-66 absorption from examples/arts-cat-data/lines/lines.py")
163
164"""
165That's it!  You are done and have reached the end of this example.  Everything
166below here is just to ensure that ARTS does not break in the future.  It can
167be safely ignored
168
169"""
170# Save test results
171# ws.propmat_clearsky.value.data.savexml("lines_test_result.xml", type="zascii")
172
173# test that we are still OK
174propmat_clearsky_agenda = pyarts.arts.Tensor4()
175propmat_clearsky_agenda.readxml("lines_test_result.xml")
176assert np.allclose(
177    propmat_clearsky_agenda, ws.propmat_clearsky.value.data
178), "O2 Absorption has changed"