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

#include <skphasematrix.h>

Inheritance diagram for skOpticalProperties:
skOpticalProperties_AerosolProfile skOpticalProperties_Convolved skOpticalProperties_ConvolvedDiscreteWavelenCachedState skOpticalProperties_HenyeyGreenstein skOpticalProperties_HitranChemical skOpticalProperties_MartHybridProfile skOpticalProperties_MultipleOverlappingSpectra skOpticalProperties_O3_BassPaurQuadratic skOpticalProperties_ParticleBase skOpticalProperties_RayleighDryAir skOpticalProperties_SimpleRayleigh skOpticalProperties_TabulatedCrossSectionAndPhaseMatrix_BaumDB skOpticalProperties_TabulatedExtinction_HeightWavelength skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength skOpticalProperties_UserDefinedAbsorption

Public Member Functions

 skOpticalProperties ()
 
bool GetRotatedPhaseMatrix (double wavenum, double mu, double muprime, double dphi, skRTPhaseMatrix *rotatedmatrix, size_t threadindex)
 Returns the rotated phase matrix necessary for scattering. More...
 
void CheckCosineRange (double *mu)
 
bool IsDeltaFunctionForwardScatter () const
 Returns true if this cross-section has a delta function forward scatter element.
 
virtual bool SetAtmosphericState (skClimatology *neutralatmosphere, const GEODETIC_INSTANT &pt, bool *crosssectionschanged)=0
 Sets the atmospheric state and location for calculating cross-sections, usually temperature, pressure and position. More...
 
virtual bool UpdateInternalClimatology (const GEODETIC_INSTANT &pt)=0
 
virtual bool CalculateCrossSections (double wavenumber, double *absxs, double *extxs, double *scattxs, size_t threadindex)=0
 Calculate cross-sections at the specified wave-number. More...
 
virtual bool CalculateCrossSectionsArray (const std::vector< double > &wavenumber, std::vector< double > *absxs, std::vector< double > *extxs, std::vector< double > *scattxs)
 Calculate cross-sections at the specified array of wave-numbers. More...
 
virtual bool CalculatePhaseMatrix (double wavenumber, double cosscatterangle, skRTPhaseMatrix *phasematrix, size_t threadindex)
 Calculate the phase matrix at the specified wavenumber and scattering angle. More...
 
virtual bool IsScatterer () const =0
 Returns true if this particles scatters radiation.
 
virtual bool IsAbsorber () const =0
 Returns true if this particles absorbs radiation radiation.
 

Detailed Description

Overview
The skOpticalProperties class is a base class that provides an interface for calculating the scattering, absorption and extinction properties of individual atoms, molecules or particles in the atmosphere. The class is one of the foundations of the radiative transfer engines. A user will typically combine the cross-sections of individual atoms, molecules or particles provided by this set of classes with appropriate number densities to calculate extinction, scattering and extinction per cm. Users will first set the location of the calculation in the atmosphere using method SetAtmosphericState or UpdateInternalClimatology and then calculate cross-sections and phase matrices using CalculateCrossSections and CalculatePhaseMatrix. A helper function, GetRotatedPhaseMatrix, is provided to rotate phase matrices from one reference frame to another
Atmospheric State
Most atoms, molecules or particles have absorption, scattering or extinction cross-sections that depend upon atmospheric condition and this detail must be modelled by this class. For example, many cross-sections depend upon temperature, pressure or both. The skOpticalProperties class uses a climatology class, see SetAtmosphericState, derived from class skClimatology to provide information about atmospheric state. Most users will normally call SetAtmosphericState once to initialize the skOpticalProperties class and then use UpdateInternalClimatology to "move" aroudn teh atmosphere. The difference is that SetAtmosphericState will refresh the climatologies internal cache, which can be computationally expensive, while UpdateInternalClimatology simply interpolates within the cached model, which is normally much quicker.
Multi-Threading in Wavelength Only
The optical property code was upgraded in early 2014 to be thread safe for multiple wavelength calculations at one geophysical location. This means that methods CalculateCrossSections and CalculatePhaseMatrix, which calculate properties at the current location, are thread safe but methods SetAtmosphericState and UpdateInternalClimatology are not thread safe. Users will typically arranage their code so they multi-thread over wavelength calculations at one location and then update the location within a single thread.
Delta Function Forward scatter
An optimization, SetDeltaFunctionForwardScatterFraction(), is provided for derived aerosol classes that have strong forward scatter which can be approximated by a delta function. This forward scattering fraction is approximated as "unscattered" light that is unmodified by the species presence.
Convolution of Optical Properties with Instrument Point Spread Functions
We have developed a set of interfaces that convolve optical properties with (instrument) point spread functions. This functionality relies on two interface classes, skWavelengthToPSF_Table which describes the instrument that measured the cross-section info and skOpticalProperty_AdditionalStateInfo which generates unique storage keys from the atmospheric state for caching convolved cross-sections. These two interfaces, or derived variations, are then inherited by the cross-section classes, for example see class skOpticalProperties_O3_SciaBogumilV4. The actual convolution is performed by class skOpticalProperties_ConvolvedDiscreteWavelenCachedState and its derived classes which takes all of the above elements and behaves as a replacement for the source cross-section object except it is now convolved to the desired resolution.

Constructor & Destructor Documentation

skOpticalProperties::skOpticalProperties ( )

Initialize the base class. Initialize all numeric elements to zero and flag the class as dirty.

Member Function Documentation

bool skOpticalProperties::GetRotatedPhaseMatrix ( double  wavenum,
double  mu,
double  muprime,
double  dphi,
skRTPhaseMatrix rotatedmatrix,
size_t  threadindex 
)

Returns the rotated phase matrix necessary for scattering.

Get the phase matrix when the light is scattered from incoming zenith angle #muprime to outgoing zenith angle #mu and the change in azimuth is #dphi radians (outgoing azimuth - incoming azimuth). This applies all of the rotation matrices to ensure the Stokes vectors refer to the plane formed by the ray and the vertical. Dont ask about beams exactly in the vertical direction. I think the code fails. A description of what this code does can be found in Appendix A of reference 1.

Parameters
mucosine of the outgoing zenith angle
muprimecosine of the incoming zenith angle
dphiThe change in azimuth in radians: outgoing azimuth minus incoming azimuth in radians
rotatedmatrixReturns the phase matrix rproperly rotated so the reference polarization is in the zenith = 0 direction.t
Reference
  1. McLinden et al. A vector radiative-transfer model for the Odin/Osiris project. Can. J. Phys., 90: 375-393, 2002. doi:10.1139/P01-156

References skRTPhaseMatrix::ApplyStokesRotation(), CalculatePhaseMatrix(), CheckCosineRange(), and skRTPhaseMatrix::SetTo().

void skOpticalProperties::CheckCosineRange ( double *  mu)

Quick check to get rid of nasty round off issues in cos(zenith angle).

Referenced by GetRotatedPhaseMatrix().

bool skOpticalProperties::SetAtmosphericState ( skClimatology *  neutralatmosphere,
const GEODETIC_INSTANT &  pt,
bool *  crosssectionschanged 
)
pure virtual

Sets the atmospheric state and location for calculating cross-sections, usually temperature, pressure and position.

[NOT THREAD SAFE} Function that allows the optical properties class to update internal parameters in response to the caller changing geophysical location. This is provided so that radiative transfer models can manage cross-sections that depend upon pressure and temperature. The user (eg the radiative transfer model) will usually call SetAtmosphericState before calling CalculateCrossSections.

Parameters
neutralatmosphereA climatology passed in by the user. The optical properties class can use this class if they wish to lookup parameters of interest. The climatology will usually support, pressure, temperature and density.
ptThe time and location at which the next set of cross-sections will be needed. Note that the height field in point will be valid (as this is often used to get the pressure and temperature).
crosssectionschangedreturns true if the new geophysical location will cause a change in cross-section. Several species (eg Rayleigh scattering) are completely unaffected by changes in location.

Implemented in skOpticalProperties_MultipleOverlappingSpectra, skOpticalProperties_Convolved, skOpticalProperties_O3_BassPaurQuadratic, skOpticalProperties_HenyeyGreenstein, skOpticalProperties_RayleighDryAir, skOpticalProperties_SimpleRayleigh, skOpticalProperties_TabulatedExtinction_HeightWavelength, skOpticalProperties_AerosolProfile, skOpticalProperties_UserDefinedAbsorption, skOpticalProperties_HitranChemical, skOpticalProperties_IceCrystal, skOpticalProperties_ConvolvedDiscreteWavelenCachedState, skOpticalProperties_TabulatedCrossSectionAndPhaseMatrix_BaumDB, skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength, skOpticalProperties_MieAerosol, and skOpticalProperties_MartHybridProfile.

Referenced by skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength::SetAtmosphericState(), skOpticalProperties_ConvolvedDiscreteWavelenCachedState::SetAtmosphericState(), skOpticalProperties_HenyeyGreenstein::SetAtmosphericState(), skOpticalProperties_Convolved::SetAtmosphericState(), and skOpticalProperties_MultipleOverlappingSpectra::SetAtmosphericState().

bool skOpticalProperties::UpdateInternalClimatology ( const GEODETIC_INSTANT &  pt)
pure virtual
Function that allows the optical properties class to update any internal
climatologies it may be using. This is useful for optical properties that use
internal climatologies to store various parameters (eg aerosols that store geographical distributions
of mode radius and mode width). The call to UpdateInternalClimatology differs from SetAtmosphericState
in its expected usage: a call to UpdateInternalClimatology configures internal climatologies so they
can quickly service the many subsequent calls to SetAtmosphericState.
Parameters
ptThe time and location at which the next set of cross-sections will be needed. Note thatthe height field is usually ignored as all internal climatologies are expected to cache height profiles of their respective parameters.
Returns
True if success otherwise false.

Implemented in skOpticalProperties_MultipleOverlappingSpectra, skOpticalProperties_Convolved, skOpticalProperties_O3_BassPaurQuadratic, skOpticalProperties_HenyeyGreenstein, skOpticalProperties_RayleighDryAir, skOpticalProperties_SimpleRayleigh, skOpticalProperties_TabulatedExtinction_HeightWavelength, skOpticalProperties_AerosolProfile, skOpticalProperties_UserDefinedAbsorption, skOpticalProperties_HitranChemical, skOpticalProperties_IceCrystal, skOpticalProperties_ConvolvedDiscreteWavelenCachedState, skOpticalProperties_TabulatedCrossSectionAndPhaseMatrix_BaumDB, skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength, skOpticalProperties_MieAerosol, and skOpticalProperties_MartHybridProfile.

Referenced by skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength::UpdateInternalClimatology(), skOpticalProperties_ConvolvedDiscreteWavelenCachedState::UpdateInternalClimatology(), skOpticalProperties_HenyeyGreenstein::UpdateInternalClimatology(), skOpticalProperties_Convolved::UpdateInternalClimatology(), and skOpticalProperties_MultipleOverlappingSpectra::UpdateInternalClimatology().

bool skOpticalProperties::CalculateCrossSections ( double  wavenumber,
double *  absxs,
double *  extxs,
double *  scattxs,
size_t  threadindex 
)
pure virtual

Calculate cross-sections at the specified wave-number.

The main function of the class. The user calls this function so the optical properties object can
calculate and update its three cross-sections: absorption, scattering and extinction.
The user may fetch the calculated cross-sections  by calling #AbsorptionCrossSection, #ScatteringCrossSection

and #ExtinctionCrossSection.

There is no requirement that the class generate physically meaningful cross-sections where the sxtinction is the sum of the absorption and the scattering (although this will normally be the case)

Well-written classes will check that the user is not calling for a calculation under identical conditions.

Parameters
wavenumberThe wavenumber (cm-1) at which the calculations are required.
absxsReturns the absorption cross-section in cm-2
extxsReturns the extinction cross-section in cm-2
scattxsReturns the scattering cross-section in cm-2
threadidPasses in the 0 based index of this thread. This is used by derived classes to store thread local storage. Default value is zero.
Returns
True if success otherwise false.

Implemented in skOpticalProperties_MultipleOverlappingSpectra, skOpticalProperties_Convolved, skOpticalProperties_O3_BassPaurQuadratic, skOpticalProperties_HenyeyGreenstein, skOpticalProperties_RayleighDryAir, skOpticalProperties_SimpleRayleigh, skOpticalProperties_TabulatedExtinction_HeightWavelength, skOpticalProperties_AerosolProfile, skOpticalProperties_UserDefinedAbsorption, skOpticalProperties_HitranChemical, skOpticalProperties_IceCrystal, skOpticalProperties_ConvolvedDiscreteWavelenCachedState, skOpticalProperties_TabulatedCrossSectionAndPhaseMatrix_BaumDB, skOpticalProperties_MieAerosolCached, skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength, skOpticalProperties_MieAerosol, and skOpticalProperties_MartHybridProfile.

Referenced by skOpticalProperties_TabulatedPhaseMatrix_HeightWavelength::CalculateCrossSections(), skOpticalProperties_AerosolProfile::CalculateCrossSections(), skOpticalProperties_HenyeyGreenstein::CalculateCrossSections(), and CalculateCrossSectionsArray().

bool skOpticalProperties::CalculateCrossSectionsArray ( const std::vector< double > &  wavenumber,
std::vector< double > *  absxs,
std::vector< double > *  extxs,
std::vector< double > *  scattxs 
)
virtual

Calculate cross-sections at the specified array of wave-numbers.

Calculate the cross-sectios for an array of wavenumbers. The defualt implementation is a single threaded loop to calculate the cross-section for each wavenumber separately. Optimized versions, for Hitran and Voigt lineshapes for example, override this member and provide code optimized, multi-threaded versions.

Reimplemented in skOpticalProperties_HitranChemical.

References CalculateCrossSections().

bool skOpticalProperties::CalculatePhaseMatrix ( double  wavenumber,
double  cosscatterangle,
skRTPhaseMatrix phasematrix,
size_t  threadindex 
)
virtual

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