skOpticalProperties  2.1
Public Member Functions | List of all members
skSpectralLineShape Class Referenceabstract

#include <skspectralline.h>

Inheritance diagram for skSpectralLineShape:
skSpectralLineShape_HumlicekWells skSpectralLineShape_VoigtKuntz

Public Member Functions

virtual bool LineShapeFunction (double nu, double *uservalue, const skSpectralLine *spectralline, skSpectralLineShapeStorageBuffer *storagebuffer)=0
 Storage buffer from an earlier call to ConfigureStorageBuffer. More...
 
virtual bool SetParentMaxLineStrength (double parentmaxlinestrength, const skSpectralLine *spectralline, skSpectralLineShapeStorageBuffer *storagebuffer) const =0
 Storage buffer from an earlier call to ConfigureStorageBuffer. More...
 
virtual bool AddLineShapeFunctionArray (const std::vector< double > &nu, std::vector< double > *uservalue, const skSpectralLine *spectralline, skSpectralLineShapeStorageBuffer *storagebuffer)
 Storage buffer from an earlier call to ConfigureStorageBuffer. More...
 
virtual bool ConfigureLineParameters (skSpectralLine *spectralline, double temperature, double pressure, const GEODETIC_INSTANT &geopt, skClimatology *atmopshericstate, skSpectralLineShapeStorageBuffer *storagebuffer)=0
 and store it in this buffer. More...
 
virtual bool CreateStorageBuffer (skSpectralLineShapeStorageBuffer **storagebuffer)=0
 and store it in this buffer. More...
 

Detailed Description

A base class used to implement line shape functions. Many of the derived classes will implement Voigt, Lorenz or Gauss but many other options, like user defined shapes can be added at later dates.

Multi-threading
This class will often form the work horse of HITRAN calculations and it will be critical that speed is fully optimized in the class. Part of that equation is that the LineShapeFunction method must be thread safe so we can have multiple threads running simultaneously. To help develop multi-threading code the skSpectralLineShape class implements the line-shape function as const, implying it is intrinsically thread safe. In reality this is not quite true as the method request that the user pass in the class specific storage buffer created by CreateStorageBuffer. This buffer will have all of the information that can be cached one we know atmospheric state and it will also hold any internal structures (eg lookup tables) that must be changed during processing of method LineShapeFunction. The buffer code must ensure that changes to internal structures within this buffer are properly protected with mutexes etc.

Member Function Documentation

virtual bool skSpectralLineShape::LineShapeFunction ( double  nu,
double *  uservalue,
const skSpectralLine spectralline,
skSpectralLineShapeStorageBuffer storagebuffer 
)
pure virtual

Storage buffer from an earlier call to ConfigureStorageBuffer.

[THREAD-SAFE] Calculate the Line Shape Function for a given spectral line. This interface is for single wave-number processing and is suitable for the Monte-Carlo and Successive Order engines. The controlling software must successfully called ConfigureAtmopshericState and ConfigureStorageBuffer before calling LineShapeFunction. Typically, atmospheric state information, which is common to all of the spectral lines processed, is stored within the derived SpectralLineShape object while line specific information for the given atmospheric state is stored inside the storage buffer. This function must be implemented so it is thread safe as multiple threads may be calculating LineShape for different wavenumbers or spectral lines simultaneaously

Parameters
nuThe wavenumber at which to calculate the lineshape. We dont specify vacuum or air but it should be the same as the optical properties. HITRAN cross-sections are specified in vacuum. Many other cross-sections, especially in the visible, are specified at STP.
uservaluereturns the line shape value at this wavenumber. The line shape is normalized so its total area is unity.
spectrallineThe spectral line (eg HITRAN line) object that is "using" this LineShape object. Note that one instance of skSpectralLineShape may be shared between many different spectral lines.
storagebufferAn object created by this spectral line shape object that is used to cache information about the specific spectral line being processed. Access to the cached information must be thread safe using mutexes etc as it is possible that multiple threads processing multiple wavenumbers are accessing the cached object simultaneously.
Parameters
nuCalculate line shape function at this wavenumber
uservaluereturns the line shape value in this variable
spectrallineSpectral line for line shape function

Implemented in skSpectralLineShape_VoigtKuntz.

Referenced by AddLineShapeFunctionArray().

virtual bool skSpectralLineShape::SetParentMaxLineStrength ( double  parentmaxlinestrength,
const skSpectralLine spectralline,
skSpectralLineShapeStorageBuffer storagebuffer 
) const
pure virtual

Storage buffer from an earlier call to ConfigureStorageBuffer.

[THREAD-SAFE] Allows the line shape object to update the useful wavenumber limits for future Voigt/lineshape function evaluations. This can be a signifcant processing optimization. This function is usually invoked after the user has moved to a different point in the atmosphere and [pressure and temperature hve changed.

Parameters
parentmaxlinestrengthThe maximum line strength considered for this micro-window calculation. The parent classes have passed in the "brightest" line in the microwindow. Given this brightness we can limit the range of wavenumbers that we need to evaluate this spectral line and still keep the calculation within a certain threshold/tolerance.
spectrallineThe spectral line (eg HITRAN line) object that is "using" this LineShape object. Note that one instance of skSpectralLineShape may be shared between many different spectral lines.
storagebufferAn object created by this spectral line shape object that is used to cache information about the specific spectral line being processed. Access to the cached information must be thread safe using mutexes etc as it is possible that multiple threads processing multiple wavenumbers are accessing the cached object simultaneously.
Parameters
spectrallineSpectral line for line shape function

Implemented in skSpectralLineShape_VoigtKuntz.

bool skSpectralLineShape::AddLineShapeFunctionArray ( const std::vector< double > &  nu,
std::vector< double > *  uservalue,
const skSpectralLine spectralline,
skSpectralLineShapeStorageBuffer storagebuffer 
)
virtual

Storage buffer from an earlier call to ConfigureStorageBuffer.

[THREAD-SAFE] Calculate the Line Shape Function for an array of wavenumbers. Returns the lineshape in array uservalue. This function replicates function LineShapeFunction except this method provides a derived class the ability to optimize the line shape code across an array of wavenumbers. This can be a significant saving when finding the X,Y regions of the Voigt function for example. Keep in mind that one line shape object is shared between many spectral lines and that the code will be possibly running in multiple threads processing muliple spectral lines simultaneously. A default implementation is provided which simply loops and calls LineShapeFunction.

Parameters
nuThe array of wavenumbers at which to calculate the lineshape. We dont specify vacuum or air but it should be the same as the optical properties. HITRAN cross-sections are specified in vacuum. Many other cross-sections, especially in the visible, are specified at STP.
uservaluereturns the array of line shape value. It will be same size as "nu". Note we only use the resize method to avoid unnecessary memory allocations. The line shape is normalized so its total area is unity.
spectrallineThe spectral line (eg HITRAN line) object that is "using" this LineShape object. Note that one instance of skSpectralLineShape may be shared between many different spectral lines.
storagebufferAn object created by this spectral line shape object that is used to cache information about the specific spectral line being processed. Access to the cached information must be thread safe using mutexes etc as it is possible that multiple threads processing multiple wavenumbers are accessing the cached object simultaneously.
Parameters
nuCalculate line shape function at this wavenumber
uservaluereturns the line shape value in this variable
spectrallineSpectral line for line shape function

Reimplemented in skSpectralLineShape_VoigtKuntz.

References LineShapeFunction().

virtual bool skSpectralLineShape::ConfigureLineParameters ( skSpectralLine spectralline,
double  temperature,
double  pressure,
const GEODETIC_INSTANT &  geopt,
skClimatology *  atmopshericstate,
skSpectralLineShapeStorageBuffer storagebuffer 
)
pure virtual

and store it in this buffer.

[NOT THREAD-SAFE] Extract all of the necessary line parameters from the atmospheric state and spectral line. If necessary the information can be stored in the storage buffer and this storage buffer instance will be passed to future calls to LineShapeFuction. We would expect that just about all derived classes will extract temperature, SKCLIMATOLOGY_TEMPERATURE_K, and most will extract pressure, SKCLIMATOLOGY_PRESSURE_PA from atmosphericstate. Derived classes will probably extract relevant spectral line info from spectral line and possibly generate intermediate results which are then stored in the storage buffer. This function does not need to be thread safe in the sense that

Parameters
spectrallineThe line parameters
temperatureThe temperature at geopt (as an optimization)
pressureThe pressure at geopt (as an optimization).
geoptGet atmopsheric state at this point
atmopshericstateUse this climatology to get atmopsheric state

Implemented in skSpectralLineShape_VoigtKuntz, and skSpectralLineShape_HumlicekWells.

virtual bool skSpectralLineShape::CreateStorageBuffer ( skSpectralLineShapeStorageBuffer **  storagebuffer)
pure virtual

and store it in this buffer.

[NOT THREAD-SAFE] Function to create the line shape storage buffer for the spectral line. All storage buffers must derive from skSpectralLineShapeStorageBuffer, we provide templatec class skSpectralLineShapeStorageBuffer_Type for this purpose but users can provide their own solution if desired. If the creation is valid then the pointer to the storage buffer object is returned in storage buffer with a reference count of 1. The calling code must release the storage buffer with a call to "Release". This function does not need to be thread-safe.

Implemented in skSpectralLineShape_VoigtKuntz, and skSpectralLineShape_HumlicekWells.


The documentation for this class was generated from the following files: