Py4CAtS --- Python for Computational ATmospheric Spectroscopy

lbl2od scheme
[Image: DLR]

Main Scripts/Functions: From Hitran/Geisa to Optical Depths

Except for the first and fifth items the name of the "main" function used in the (I)Python shell/interpreter is identical to the name of the script/module used in the Unix/Linux shell/terminal/console (except for the file extension .py).
(For example, lbl2xs is the "main" function of the lbl2xs.py module.)
atmos1D.py and atmRead
Read atmospheric data file(s) in xy tabular ascii format: extract profiles, interpolate to new altitude grid, save in xy or namelist format.
(Usually not required from the Unix/Linux shell, but "mandatory" as a function in the interpreter)
higstract
higstract (extract, select) lines of a certain molecule (and isotope) and/or wavenumber range from line parameter database.
(To avoid name clashes with numpy's extract function, the module and corresponding function is now called higstract, short for HItran-GeiSa-exTRACT)
(In contrast to the "low-level" hitran and geisa scripts/functions (see below) molecule (and isotope) can be specified by their chemical names!)
lbl2xs
Line-by-line (lbl) cross sections for some molecule(s) and several p, T
lbl2od
Computation of line-by-line optical depth due to molecular absorption (combines lbl2xs, xs2ac, ac2od)
(d)od2ri
Evaluate Schwarzschild integral: integrate transmission weighted optical depth along line-of-sight

Further Conversion Scripts with Corresponding Functions

Note: The functions inside the *2od.py files compute delta optical depths, hence most are called ...2dod, whereas the scripts have an option to save total or (ac)cumulated optical depths.
xs2ac
Sum up cross sections to absorption coefficients
ac2od
Integrate absorption coefficients to optical depth
ac2wf
Compute weighting funtions given absorption coefficients along with atmospheric data (altitudes)
xs2od
Sum up cross sections to absorption coefficients and integrate to optical depth
lbl2ac
Lbl cross sections, then sum up to absorption coefficients

radiance2radiance
Convert radiance (intensity) vs. wavenumber to radiance vs frequency etc.
radiance2Kelvin
Convert radiance (intensity) to equivalent blackbody temperatures according to Planck
cgsUnits
Conversion of (scalar or array) physical values to different units

Further Executable Scripts and Functions

The first group of modules define subclassed NumPy arrays saving the data (line parameters, cross sections, etc.) along with some attributes and provide functions to read, write, plot and 'manipulate' the data:
lines
Read molecular spectroscopic line parameters (from Hitran, Geisa, ... extract(s)) and convert to new pressure/temperature
xSection
Read and write / plot molecular cross sections (e.g., to reformat or interpolate)
absCo
Read and write / plot absorption coefficients
oDepth
Read and write / plot optical depth, optionally transform differential <--> accumulated --> total optical depth
wgtFct
Read and write / plot weighting functions
radInt
Read and write / plot radiance (intensity)

Further modules that can be used as command line script and as function inside the (I)Python interpreter:
hitran
Extract lines of a certain molecule (and isotope) and/or wavenumber range from the HITRAN database
geisa
Extract lines of a certain molecule (and isotope) and/or wavenumber range from the GEISA databank
plot_atlas
Plot line data, i.e., line position vs strength in 'atlas' style.
(Note:This version utilizes the xmgr plotting tool (a.k.a. ACE/gr, further developed into the GRACE tool). Alternatively use the atlas function in the lbl/lines.py module)
planck
Compute Planck's black body function as a function of wavenumber (or frequency, wavelength) for given temperature(s)
srf
A collection of spectral response functions
molecules
A dictionary of dictionaries containing molecular data (id numbers, mass, ....) along with some convenience functions

Supplementary Modules

(None of these modules is executable on the command line)
lineshapes
Lorentz, Gauss, Voigt, and ... line profiles (normalized to one)
racef
Rational approximations for the complex error function (Humlicek, Weideman, ...)
rayleigh
Rayleigh cross section, absorption coefficient, and optical depth.
limb
vertical optical depth to limb transmission and effective height
lagrange_interpolation
Linear, quadratic and cubic Lagrange interpolation for equidistant/uniform grids
convolution
Convolution of monochromatic spectrum/spectra with Box, Triangle, Gaussian spectral response functions of constant width
convolve_grating
Convolution of monochromatic spectrum/spectra with Gaussian spectral response functions of constant resolution
command_parser
Command line interpreter, esp. options, written ontop of Python's getopt module
aeiou
Advanced extended input/output utility functions
struc_array
Functions to read and ... structured arrays from file
grid
Functions to handle equidistant/uniform grids
ir
Constants for infrared spectroscopy and radiative transfer
misc
Miscellaneous ...
moreFun
More (elementary or special) functions
pairTypes
Three classes for PairOfInts, PairOfFloats, Intervals

The Py4CAtS Package

Py4CAtS is organized as a Python package, i.e. all modules listed above are grouped in three distinct directories:
 
Package Contents
       
art (package)
var (package)
lbl (package)


Some Remarks on the Executable Scripts


DATA

To use these scripts, you need molecular spectroscopic line parameters (essentially line positions and strengths) and atmospheric data comprising pressure, temperature, and molecular concentrations as a function of altitude.
See the data directory for the six AFGL atmospheres (with full 50 level and reduced versions), some "representative" line parameter files (generated by the higstract.py module, usually irrelevant in the (I)Python shell), and solar irradiance spectra (Kurucz data taken from Modtran, important for SWIR/NIR applications).

Executing Py4CAtS

Py4CAtS can be used in two ways, from the Unix/Linux (or Windows/Mac) console/terminal or (much better, more flexible, ...!) inside the (I)Python interpreter, see the py4cats.pdf chapters 5 and 6 or the IPython demo.

(I)Python, Jupyter shell (or notebook)
Basically you have to add the directory containing Py4CAtS (here assuming the projects directory in my home directory) to Python's search path, i.e.
sys.path.insert (0, '/home/franz/projects')
or
sys.path.append ('/home/franz/projects')
and then you can import the required modules. In the IPython interpreter you can execute these two steps with the command
from py4cats import *
See section 6.1 in the pdf manual, how this setup is done more efficiently.
Unix etc. shell
NOTE: Using Py4CAtS inside the (I)Python (or Jupyter) shell (or notebook) is much better, more flexible, .... This mode is “historical” and probably not maintained forever!

The executable scripts are in ../bin (relative to this doc directory!)
To add this directory to your search path, you have to change the shell's PATH variable, e.g.
setenv PATH ${PATH}:${py4catsHome}/bin
or
setenv PATH ${py4catsHome}/bin:${PATH}
Here ${py4catsHome} denotes the directory where you have stored the package (something like /a/very/long/path/to/py4cats/).

(For the bash or korn shell use the equivalent export command). Ideally add this statement to your .tcshrc (or .cshrc or .bashrc) file, because otherwise you have to redo this statement whenever you start a new terminal/console.

Note that the executables in this bin directory should be symbolic links to the corresponding scripts in the src directory (with the .py extension omitted). If these links did not survive the packing and unpacking to/from the tarball, you can restore them by, e.g.,
cd bin; ln -s ../lbl/lbl2xs.py lbl2xs
(Also see the 1.ReadMe file in the bin directory.)

(Strictly speaking the change of the search path is not required. You can always start a script by giving the full path name, e.g.
/a/very/long/path/to/py4cats/bin/lbl2xs
or equivalently
/a/very/long/path/to/py4cats/src/lbl2xs.py,
but thats boring, not really fun, ....)

Ideally the Py4CAtS scripts should run on any computer. Well, almost any, of course you should have Python along with numpy (and scipy occasionally ....).
In order to save the optical depth data using netcdf format, you also need an appropriate module such as Scientific.IO.NetCDF (from K. Hinsen's ScientificPython; Alternatively pynetcdf might help ....).
For plotting (e.g. atmospheric data, line data, spectra) you need matplotlib. (Alternatively lines can be plotted with ACE/gr = xmgr using the plot_atlas script or its aceGr_atlas function; Both scripts have slightly different capabilities (pro's and con's), but none is perfect!)


Documentation and Some Questions

Some Questions


What's new?

March 2021
Source code now reorganized as a package
Source files are now distributed over three subdirectories
  • lbl: modules related to lbl computations incl. Hitran/Geisa database access, Voigt routines etc.;
  • art: modules related to atmospheric radiative transfer;
  • var: variliary modules that should/could be useful in any context, e.g. input/output routines.
The setup module py4cats.py is not required anymore, import of the Py4CAtS module is now organized by the __init__.py files.

Spring - Summer 2021 (see What's new? for a full listing)
  Plot functions
atmPlot, acPlot, odPlot, riPlot, xsPlot functions have an additional argument **kwArgs (passed thru to MatPlotLib's functions)
acPlot, odPlot, xsPlot with an additional argument xUnit (instead of flag mue or nm)
  Module var/aerosol.py
new module for aerosol optical depth using simple power law (Angstrom coefficient)
  Module lbl/lbl2xs.py
function lbl_brute: handling/selection of "beyond Voigt" line shapes changed;
  Module lbl/lines.py
better support of "beyond Voigt" parameters;
new function llInfo
  Module art/limb.py:
new module for limb (occultation) transmission and effective height
  Module lbl/molecules.py
new molecules (hitran20, geisa19) added
  Module art/oDepth.py
class odArray with new attribute column density;
convolve method with default Gauss;
new function odConvolve (calls class method);
  Module art/od2ri.py
completely rewritten with added support for surface reflection etc
  Module art/rayleigh.py
new module for Rayleigh extinction
  Module art/radInt.py
class riArray with new method noise;
convolve method with default Gauss;
new function riConvolve (calls class method);
function riRead now returns a dictionary of riArray's if all entries of the pickle file have a `key`;
function riSave: if called with a dictionary of riArray's, save each as dictionary with an extra `key`
  Module lbl/sdr.py
new module for speed-dependent Voigt and Rautian functions

Fall 2021 (see What's new? for a full listing)
  Module lbl/lbl2od.py
three new options for function lbl2od to add cia, Rayleigh, and aerosol extinction to absorption coefficient(s) and optical depth(s)

Winter 2021/22 (see What's new? for a full listing)
  Module art/atmos1D.py
The function atmPlot can plot all molecular profiles simultaneously with a call atmPlot(atmosData, what='*')
  Module art/radInt.py
new class methods dict and append for riArray
  Modules lbl/lbl2ac.py and lbl/lbl2od.py
In the corresponding functions a consistency test of atmospheric vs line data has been implemented: stop if line data are given, but no corresponding concentrations

Known Problems


... and some notes on license

© fgs   (+49-8153-28-1234)
Fri Jan 15, 2021; 12:34