ISKOpticalProperty¶

The ISKOpticalProperty interface is used to describe the absorption, extinction and scattering cross-sections of individual atoms, molecules or particles and includes support for calculating the scattering phase matrix. The optical properties are often combined with number density climatologies to produce extinction, absorption and scattering coefficents within the atmossphere. Many cross-section depend upon the prevailing atmopsheric state and this aspect is supported by the interface

Note,

Atmospheric thermal and airglow emissions are not supported by this interface but by interface ISKEmission.

Exotic atmospheric parameters such as aerosol mode radius which typically apply to only one optical property object may be defined through the optprop.SetProperty interface o fthe specific otpical property object.

class ISKOpticalProperty(name)¶

The ISKOpticalProperty constructor.

Parameters:: name (str) – The name of the optical property to be created. The name must correspond to an installed sasktranif optical property. If no name is provided then a blank ISKOpticalProperty is created. This blank value can be useful for updating climatologies with ISKEngine method AddSpecies()

AddUserDefined¶

ISKOpticalProperty.AddUserDefined(species, location) → value¶

A method to set user-supplied, custom cross-section data. This method is only supported by optical property object USERDEFINED_TABLES. The object allows you to tabulate cross-section as a function of temperature and wavelength, similar to many UV/Visible cross-sections databases. By default:

ok = userdefined_optprop.AddUserDefined( temperatures, wavelen_nm, crosssection) -> ok

Parameters:

temperature (double) – The temperature in Kelvins to be associated with this cross-section data.
wavelen_nm (array) – The array of wavelengths in nanometers of the cross-section data.

:param array crosssection: The array of cross-section data. Cross-sections must be provided as cm2 per atom/molecule/”average particle”.

Parameters:: ok (bool) – returns true if successful
Returns:: returns true if successful

CalculateCrossSections¶

ISKOpticalProperty.CalculateCrossSections(wavenumber)¶

Calculates the absorption, extinction and scattering cross-sections of one atom, molecule or “average” particle of the optical property object at the wavenumber. The cross-sectional areas are returned as cm2/particle. Users can set the location at which the cross-section is required with a prior call to SetAtmosphericState.

This method will calculates cross-sections for either a single scalar wavenumber or for an array of wavenumbers which must be in ascending wave-number order. The python and matlab code identifies if the incoming wavenumber is an array or not.

The incoming wavenumber is currently ambiguous as it refers to vacuum for some optical property objects and to air at STP for others. We know this is an issue and we will address it in the future. As a rule of thumb the UV/Visible optical property objects usually report cross-sections at STP while HITRAN and IR optical property objects report cross-section in vacuum:

ok,absxs, extxs, scatxs = optprop.CalculateCrossSections( wavenumber )

Parameters:

wavenumber (double) – The scalar or ascending array of wavenumber (cm-1) at which the cross-sections are required. As discussed above the wavenumber may refer to air at STP or vacuum depending upon context.
absxs (double) – Returns the absorption cross-section in cm2/(atom-molecule-particle) for the corresponding wavenumbers. May be NaN if there were errors.
extxs (double) – Returns the extinction cross-section in cm2/(atom-molecule-particle) for the corresponding wavenumbers. May be NaN if there were errors.
scatxs (double) – Returns the scattering cross-section in cm2/(atom-molecule-particle) for the corresponding wavenumbers. May be NaN if there were errors.
ok (bool) – returns true if successful

Returns:

returns the 4 element list [ok, absxs, extxs, scatxs]

InternalClimatology_UpdateCache¶

ISKOpticalProperty.InternalClimatology_UpdateCache(location)¶

This is a speciality function that most users will not need to use. Updates the caches of any internal climatologies used by the optical property object. For example, ice and aerosol optical properties store internal climatologies of particle size distribution, typically mode radius and mode width. This method reloads the internal caches of the internal climatologies:

ok = optprop.InternalClimatology_UpdateCache (location );

Parameters:

location (GEODETIC_INSTANT) – The location of the new cache. GEODETIC_INSTANT is a 4 element array [latitude, longitude, height_meters, mjd]. Latitude and longitude are geodetic coordinates in degrees, height_meters is height above sea-level in meters and mjd is Modified Julian Date expressed in days.
ok (bool) – Returns true if successful.

Returns:

returns true if successful

IsValidObject¶

ISKOpticalProperty.IsValidObject() → ok

Used to identify if the underlying C++ optical property is properly created. The function is primarily intended for internal usage:

ok = climate.IsValidObject();

Parameters:: ok (boolean) – The return value, true if the underlying C++ object is properly constructed otherwise false.
Returns:: returns true if successful

SetAtmosphericState¶

ISKOpticalProperty.SetAtmosphericState(atmosphere) → ok¶

Sets the ISKClimatology object that will be used as the background atmosphere in subsequent calls to CalculateCrossSections(). Many optical property objects need object atmosphere to support atmospheric temperature and several need atmospheric pressure; in prinicple the list of required parameters is unlimited but in practice we have not yet encountered a need for anything other than P and T. However, in the final analysis it is the callers responsibility to ensure that the background atmospheric climatology supports all the parameters needed by the optical property object (you should see warnings if problems occur).

It is the responsibility of the calling code to ensure the cache of the atmosphere object has been previously loaded with a call to UpdateCache before SetLocation() or CalculateCrossSections() are invoked. Note that ISKEngine objects make these calls for the user. Optical property objects avoid invocations of UpdateCache() for reasons of speed and efficiency and only call GetParameter():

ok = optprop.SetAtmosphericState ( atmosphere )

Parameters:: atmosphere (ISKClimatology) – The ISKClimatology object used to calculate atmospheric state parameters by the optical property object on subsequent calls to CalculateCrossSection. The ISKClimatology object will typically support calculation of pressure and temperature.
Returns:: returns true if successful

SetLocation¶

ISKOpticalProperty.SetLocation(location)¶

Sets the location in the atmosphere for subsequent cross section calculations. This normally translates to the location used in the background atmosphere, see ISKOpticalProperty.SetAtmopshericState(), to calculate P and T. Note that ISKEngine objects make this call for the user:

ok = optprop.SetLocation ( location )

Parameters:: location (Tuple[lat,lng,heightm, mjd]) – The location and time in the atmosphere used to perform the next cross-section calculation. The location is a 4 element array [latitude, longitude, height_meters, mjd]. Latitude and longitude are geodetic coordinates in degrees, height_meters is height above sea-level in meters and mjd is Modified Julian Date expressed in days.
Returns:: returns true if successful

SetProperty¶

ISKOpticalProperty.SetProperty(propertyname, value) → ok¶

:noindex:

Set custom properties of the optical property object. The user must refer to documentation about the specific optical property object to see what properties it supports:

ok = optprop.SetProperty(propertyname, value)

Parameters:

propertyname (string) – The name of the custom property to be modified.
value (double/array/object) – The new value of the property. The value must be a scalar double, array of doubles or a SasktranIF object

Returns:

returns true if successful