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
  7Note that this example presumes that you have set the environment variable
  8ARTS_DATA_PATH to contain a path to a local copy of both arts-cat-data and
  9arts-xml-data before you import pyarts.  Please check that this is the case
 10if the example does not work for you.  You can easily check if this path is
 11set by adding the following two lines at the top of this pyarts-controlfile:
 12
 13```
 14import os
 15print(os.environ.get("ARTS_DATA_PATH"))
 16```
 17
 18"""
 19
 20import pyarts
 21import numpy as np
 22import matplotlib.pyplot as plt
 23
 24# Initialize ARTS
 25ws = pyarts.workspace.Workspace()
 26
 27"""
 28
 29Set ws.abs_species to the species tags that you wish to use.  Pure line-by-line
 30calculations sets the species by an expanded form of the AFGL tag system in
 31ARTS.  This example sets the isotopologue to O16-O16, "O2-66", to include all
 32lines of said isotopologue into the absorption species tag list
 33
 34There are many ways to customize this tag.  The following things are examples
 35of what is possible:
 361) Change "O2-66" to "O2".  Consequence: Not just the O2-66 isotopologue is
 37    included in the absorption species tag list but all molecular oxygen lines
 38    are included.  Note that "O2-*" is the same thing as "O2".
 392) Change "O2-66" into "O2-66,O2-68".  Consequence: Not just O2-66 but also
 40    the O16-O18 isotopologue is included as the first species tag.
 41    Note that for forward calculation purposes, writing ["O2-66,O2-68"] or
 42    ["O2-66", "O2-68"] includes the same lines but changes the layout of
 43    ws.abs_lines_per_species
 443) Change "O2-66" into "O2-66-40e9-120e9".  Consequence:  Still only the O2-66
 45    isotopologue is considered, but all lines below 40 GHz and all lines above
 46    120 GHz are considered part of another species tag.  Note that you can
 47    write your list as ["O2-66-40e9-120e9,O2-66"] to still include all lines,
 48    though this would in this particular example be a trivial waste of time
 494) Change "O2-66" to "O2-Z-66".  Consequence:  You will activate Zeeman effect
 50    calculations for O2-66.  Warning: Zeeman effect calculations are slow
 51    because they require several times more calls to core line-by-line
 52    functions.  Note that one way to speed up these calculations is to combine
 53    the tags with one of the examples above.  If you write your list of species
 54    tags as ["O2-Z-66-110e9-120e9", "O2-66"], only absorption lines between
 55    110 and 120 GHz will be treated as Zeeman-affected, but the rest of the
 56    lines are still included in the calculations.
 575) Change ["O2-66"] to ["O2-66", "H2O-161"].  Consequence: The water
 58    isotopologue H1-O16-H1 is added to your list of line-by-line absorption
 59    species.  Note that you can add as many species as you wish.  Also note
 60    that you are not allowed to write "O2-66,H2O-161" but must separate this
 61    as written at the top of this listitem.
 625) Change ["O2-66"] to ["O2-66", "O2"].  Consequence: All oxygen lines are
 63    in your list of line-by-line absorption species.  Note that you can
 64    add as many species as you wish.  Also note that you are allowed to
 65    write "O2-66,O2".
 66
 67"""
 68ws.absorption_speciesSet(species=["O2-66"])
 69
 70"""
 71
 72Load the line data of the absorption tags defined in ws.abs_species into the
 73ARTS line catalog at ws.abs_lines_per_species
 74
 75The line data file is expected to be named as a line-by-line species tag.  So
 76for our species tag of "O2-66" above, the reading routine will look for the file
 77name "lines/O2-66.xml".  The search paths for these files prefer paths relative
 78to the current working directory above this available elsewhere on the system.
 79However, "lines/O2-66.xml" does exist in a fully up-to-date version of
 80arts-cat-data (if you ARTS version is recent enough) so it is likely that this
 81is the file that is selected for reading.
 82
 83The resulting ws.abs_lines_per_species will have outer size 1,
 84len(ws.abs_lines_per_species.value) == 1, after running this file as provided
 85because the size and shape of ws.abs_species is linked to the size and shape
 86of ws.abs_lines_per_species.
 87
 88If you change your tags following one of the examples above, the following
 89are the consequences:
 901) Change "O2-66" to "O2".  ws.abs_lines_per_species will now contain not just
 91    O2-66 lines but also other isotopologues.  The len of
 92    ws.abs_lines_per_species will not change.
 932) Change "O2-66" into "O2-66,O2-68".  ws.abs_lines_per_species will now
 94    contain not just O2-66 lines but also lines of O2-68.  If written as
 95    ["O2-66,O2-68"] the len of ws.abs_lines_per_species will not change.  If
 96    written as ["O2-66", "O2-68"] the len of ws.abs_lines_per_species is now 2.
 973) Change "O2-66" into "O2-66-40e9-120e9".  This will simply limit the number
 98    of lines in the line catalog.
 994) Change "O2-66" to "O2-Z-66".  The line catalog will look exactly the same
100    but the calculations inside will change significantly
1015) Change ["O2-66"] to ["O2-66", "H2O-161"].  The len of
102    ws.abs_lines_per_species is now 2 as the first entry are lines of O2-66 and
103    the second entry are lines of H2O-161
1046) Change ["O2-66"] to ["O2-66", "O2"].  The len of
105    ws.abs_lines_per_species is now 2 as the first entry are lines of O2-66 and
106    the second entry are all other lines of O2.  Note therefore that ["O2", "O2-66"]
107    also has the len 2, but that all lines are now in the first entry.
108
109"""
110ws.absorption_bandsReadSpeciesSplitCatalog(basename="lines/")
111
112"""
113
114You should generally always call this after you are done setting up your
115ws.abs_species and ws.abs_lines_per_species.  It will deal with the internal
116ARTS setup for you.  Note that the flag use_abs_lookup=1 can be passed to this
117method call to set up the agenda for USING the the lookup-table.  Without the
118flag, ARTS should be configured correctly either 1) to compute the lookup-table,
119or to 2) compute the absorption on-the-fly
120
121"""
122ws.propagation_matrix_agendaAuto()
123
124"""
125
126Compute absorption
127
128Now we can use the propagation_matrix_agenda to compute the absorption of O2-66.
129We can also use this agenda in more complicated setups that might require
130absorption calculations, but that is for other examples
131
132To just execute the agenda we need to still define its both its inputs and the
133inputs required to initialize the propagation matrix
134
135"""
136
137ws.jacobian_targets = pyarts.arts.JacobianTargets()
138ws.frequency_grid = np.linspace(40e9, 120e9, 1001)  # Frequencies between 40 and 120 GHz
139ws.ray_path_point  # No particular POSLOS
140ws.atmospheric_pointInit()
141ws.atmospheric_point.temperature = 295  # At room temperature
142ws.atmospheric_point.pressure = 1e5  # At 1 bar
143ws.atmospheric_point[ws.absorption_species[0]] = 0.21  # At 21% atmospheric Oxygen
144
145# Call the agenda with inputs above
146ws.propagation_matrix_agendaExecute()
147
148# Plot the absorption of this example
149plt.figure(1)
150plt.clf()
151plt.semilogy(ws.frequency_grid.value / 1e9, ws.propagation_matrix)
152plt.xlabel("Frequency [GHz]")
153plt.ylabel("Absorption [1/m]")
154plt.title("O2-66 absorption from examples/arts-cat-data/lines/lines.py")
155
156"""
157That's it!  You are done and have reached the end of this example.  Everything
158below here is just to ensure that ARTS does not break in the future.  It can
159be safely ignored
160
161"""
162# Save test results
163# ws.propagation_matrix.savexml("lines_test_result.xml", type="ascii")
164
165# test that we are still OK
166propagation_matrix_agenda = \
167    pyarts.arts.PropmatVector.fromxml("lines_test_result.xml")
168assert np.allclose(
169    propagation_matrix_agenda, ws.propagation_matrix
170), "O2 Absorption has changed"