Usage

Acknowledgements

ISARA is being developed in collaboration with the Office of Naval Research, Oak Ridge Associated Universities, NASA Langley Research Center, and the University of Arizona.

Installation

To use ISARA, download the source files from the Repo.

Retrieve Complex Refractive Index

ISARA.Retr_CRI(wvl_dict, val_wvl, optical_measurements, sd, dpg, CRI_p, size_equ, nonabs_fraction, shape, rho, num_theta, path_optical_dataset, path_mopsmap_executable)

Returns aerosol particle real and imaginary refractive index from three scattering coefficeint measurements, three absorption coefficient measurements, a measured number concentration for an aerosol size distribution. WARNINGS: 1) numpy must be installed to the python environment 2) mopsmap_wrapper.py must be present in a directory that is in your PATH

Parameters:

  • wvl_dict (numpy dictionary) – Dictionary of wavelengths associated with each of the scattering and absorption measurements

  • val_wvl (numpy dictionary) – Dictionary of wavelengths associated with validation measurements

  • optical_measurements (numpy dictionary) – Dictionary containing measured dry scattering and absorption coefficients in m^-1; NOTE: There should be one key per channel (e.g., optical_measurements[‘dry_meas_sca_coef_450_m-1’], optical_measurements[‘dry_meas_abs_coef_470_m-1’], etc.)

  • sd (numpy dictionary) – Dictionary containing the modal size resolved number concentrations in m^-3; NOTE: there should be one key for each measurement mode

  • dpg (numpy dictionary) – Dictionary containing the modal geometric mean particle diameters of each size bin in nm; NOTE: there should be one key for each measurement mode

  • CRI_p (numpy array) – 2-D array containing the prescribed RRI and IRI range to be searched

  • nonabs_fraction (numpy dictionary) – Dictionary of integers indicating the desired non-absorbing fraction for each size mode; NOTE: there should be one key for each measurement mode

  • shape (numpy dictionary) – String indicating the desired particle shape(s) for each size mode; NOTE: there should be one key for each measurement mode

  • rho (numpy dictionary) – Double indicating the desired particle density in g m^-3 for each size mode; NOTE: there should be one key for each measurement mode

  • num_theta (numpy int) – Integer indicating the number of phase function angles to provide

  • path_optical_dataset (str) – String indicating the path for the optical dataset required for MOPSMAP

  • path_mopsmap_executable (str) – String indicating the path for the mopsmap.exe file

Returns:

Dictionary (Results) with the retrieved complex refractive index, calculated scattering and absorption coefficients in native measurements, and calculated single scattering albedo and extinction coefficients in measured and validation wavelengths

Return type:

numpy dictionary

Retrieve Hygroscopicity

ISARA.Retr_kappa(wvl_dict, val_wvl, optical_measurements, sd, dpg, RH, kappa_p, CRI_d, size_equ, nonabs_fraction, shape, rho, num_theta, path_optical_dataset, path_mopsmap_executable)

Returns aerosol particle hygroscopic growth factor from a humdified scattering coefficeint measurement, dry complex refractive index, and a measured number concentration for an aerosol size distribution. WARNINGS: 1) numpy must be installed to the python environment 2) mopsmap_wrapper.py must be present in a directory that is in your PATH.

Parameters:

  • wvl_dict (numpy dictionary) – Dictionary of wavelengths associated with each of the scattering and absorption measurements

  • val_wvl (numpy dictionary) – Dictionary of wavelengths associated with validation measurements

  • optical_measurements (numpy dictionary) – Dictionary containing measured dry scattering and absorption coefficients in m^-1; NOTE: There should be one key per channel (e.g., optical_measurements[‘wet_meas_sca_coef_450_m-1’] etc.)

  • sd (numpy dictionary) – Dictionary containing the modal size resolved number concentrations in m^-3; NOTE: there should be one key for each measurement mode

  • dpg (numpy dictionary) – Dictionary containing the modal geometric mean particle diameters of each size bin in nm; NOTE: there should be one key for each measurement mode

  • RH (int) – Array containing the percent relative humidity associated with the measured humidified scattering coefficients

  • kappa_p (numpy array) – Array containing the desired kappa range to be searched.

  • CRI_d (numpy array) – Array containing the desired dry RRI and IRI.

  • nonabs_fraction (numpy dictionary) – Dictionary of integers indicating the desired non-absorbing fraction for each size mode; NOTE: there should be one key for each measurement mode

  • shape (numpy dictionary) – String indicating the desired particle shape(s) for each size mode; NOTE: there should be one key for each measurement mode

  • rho (numpy dictionary) – Double indicating the desired particle density in g m^-3 for each size mode; NOTE: there should be one key for each measurement mode

  • num_theta (int) – Integer indicating the number of phase function angles to provide

  • path_optical_dataset (str) – String indicating the path for the optical dataset required for MOPSMAP

  • path_mopsmap_executable (str) – String indicating the path for the mopsmap.exe file

Returns:

Real refractive index, imaginary refractive index, calculated scattering and absorption coefficients in native measurements, and calculated single scattering albedo and extinction coefficients in all wavelengths

Return type:

numpy dictionary

Forward Model for Aerosol Optial Properties

mopsmap_wrapper.Model(wvl, size_equ, dndlogdp, dpg, RRI, IRI, nonabs_fraction, shape, density, RH, kappa, num_theta, path_optical_dataset, path_mopsmap_executable)

Interface with the Modeled Optical Properties of ensembles of Aerosol Particles (MOPSMAP) package to return forward modeled aerosol optical properties [1]. [1] Gasteiger, J., & Wiegner, M. (2018). MOPSMAP v1.0: a versatile tool for the modeling of aerosol optical properties. Geosci. Model Dev., 11(7), 2739-2762. doi:10.5194/gmd-11-2739-2018

Parameters:

  • wvl (numpy array) – Array of wavelengths in nm (e.g., 450, 470, 532, 550, 660, 700)

  • size_equ (numpy dictionary with keys for each mode as str) – size equivalence (e.g., ‘cs’)

  • dndlogdp (numpy dictionary with keys for each mode as numpy array) – log-normal concentration of each size distribution bin of each mode

  • dpg (numpy dictionary with keys for each mode as numpy array) – geometric mean diameter of each bin of each mode

  • RRI (numpy dictionary with keys for each mode as double) – refractive index, given as a string which is added in input file after ‘refrac’ (if single string it is applied to all modes, otherwise if list it is applied to each mode)

  • IRI (numpy dictionary with keys for each mode as double) – refractive index, given as a string which is added in input file after ‘refrac’ (if single string it is applied to all modes, otherwise if list it is applied to each mode)

  • nonabs_fraction (numpy dictionary with keys for each mode as int) – ratio of non-absorbing particles

  • shape (numpy dictionary with keys for each mode as str) – particle shape, given as a string which is added in input file after ‘shape’ (if single string it is applied to all modes, otherwise if list it is applied to each mode)

  • density (numpy dictionary with keys for each mode as double) – particle density (if single parameter it is applied to all modes, otherwise if list it is applied to each mode)

  • RH (double) – relative humidity used for particle resizing (if entered as zero particle is considered dry and no resizing will be performed)

  • kappa (numpy dictionary with keys for each mode as double) – particle hygroscopicity parameter (if single parameter it is applied to all modes, otherwise if list it is applied to each mode)

  • num_theta (int) – number of scattering angles in output

  • optical_dataset (str) – String indicating the path for the optical dataset required for MOPSMAP.

  • path_mopsmap_executable (str) – String indicating the path for the mopsmap.exe file.

Returns:

dictionary of all forward modeled aerosol properties available from MOSPMAP.

Return type:

numpy dictionary

Import ICARTT Files

importICARTT.imp(filename, num_time_columns)

procedure to open ICARTT file and format the data and headers into the output (output_dictionary) python dictionary.WARNINGS: 1) numpy must be installed to the python environment, 2) importICART.py and file with the corresponding filename must be present in a directory that is in your PATH

Parameters:

filename (str) – String containing the name of the desired ICARTT v2.0 (.ict) file.

Returns:

the output of this code is output_dictionary, which is a python3 dictionary containing column-arrays for each of the parameters in the .ict file

Return type:

numpy dictionary

>>> output_dictionary = importICT.imp("activate-mrg1_hu25_20200214_R0.ict")
>>> print(output_dictionary)
output_dictionary =
    {'Time_Start_seconds': array([61301., 61302., 61303., ..., 72258., 72259., 72260.]), 
    'Time_Stop_seconds': array([61302., 61303., 61304., ..., 72259., 72260., 72261.]), 
    'Latitude_THORNHILL_ deg': array([37.085528, 37.085798, 37.086065, ..., 37.126424, 37.126694, ...

Import Diameters of Aerosol Size Distribution

load_sizebins.Load(filename)

Returns an dictionary of bin diameters from a specified .csv file

Parameters:

filename (str) – String containing the name of the desired .csv file containing the size distribution bin diameters.

Return dp:

dictionary of bin diameters in micrometer.

Return type:

numpy dictionary

ISARA Data Retrievals