boreal-LOA 0.5.0

Python package of the Basic algOrithm for REtrieval of Aerosol with Lidar - an algorithm to retrieve aerosol optical and microphysical properties from lidar measurements

BOREAL package to be integrated into AUSTRAL or used independently.

General description

The BOREAL (Basic algOrithm for REtrieval of Aerosol with Lidar) algorithm is developed by the Laboratoire d'Optique Atmospherique, a joint research unit of the University of Lille and CNRS. This package retrieves particle volume size distribution (VSD) and complex refractive index (CRI = mR -imI) from lidar-derived extinction + backscattering (or + depolarisation) properties. Total volume concentration (Vt), effective radius (reff) and single-scattering albedo (SSA) are then calculated from the retrieved VSD and CRI.

Data policy

If you utilize the BOREAL retrieval products for publication purposes, we kindly request you to cite the paper listed in References and acknowledge the contribution of "University of Lille/CNRS/Laboratoire d'Optique Atmospherique". Additionally, we encourage you to consider offering co-authorship to the scientists who contributed to the development of BOREAL, if their involvement is relevant to your work. Your recognition and collaboration contribute to the advancement of scientific research and the acknowledgment of the efforts invested in the development of these resources for the community.

Structure of the package

Scripts and datasets are contained in ./boreal, where the folder forward_module includes the implementations of the sphere, spheroid and ih models. BOREAL.py and BOREAL_PC.py call the forward models and realize the inverse process.

Installation

You can clone the source coed from the repository by

Alternatively, you can install the package through PyPI. To do so, set up a Python 3.9+ environment with 'pip' available, then

BOREAL.py

The python script implementing the BOREAL method. To run the retrieval, in a python script or an interactive shell, type the following commands:

1. from boreal import BOREAL to import BOREAL
2. retrieval, fit = BOREAL.inversion(...) to perform the retrieval
3. filepath_fit = BOREAL.plot_fit(...), filepath_rtv = BOREAL.plot_rtv(...), or filepath_txt = BOREAL.export_txt(...) to visualize the results

Mandatory arguments in BOREAL.inversion():

• ext: dict, spectral extinction coefficient, the keys (str) are wavelength in nm, the values are corresponding measurements (float) in 1/Mm
• bac: dict, spectral bac. coef., the keys (str) are wavelength in nm, the values are corresponding measurements (float) in (Mm*sr)^(-1)
• aero_type: str, 'dust', 'bba', 'urban' or 'ss' (sea salt), a priori knowledge of aerosol type
• model: str, 'sphere', 'spheroid' or 'ih', forward model (scattering model) used in the inversion

Optional arguments:

• depol: None or dict (default=None), particle spectral depolarization ratio, the keys (str) are wavelength in nm, the values are corresponding measurements (float) (unit of 1)
• ext_err: None or dict (default=None), maximum measurement error in ext (three times of measurement std). None for default values.
• bac_err: None or dict (default=None), maximum measurement error in bac (three times of measurement std). None for default values.
• depol_err: None or dict (default=None), maximum measurement error in depol (three times of measurement std). None for default values.
• config: None or dict (default=None), customized configuration for implementing the retrieval

BOREAL_PC.py

The python script implementing the BOREAL-PC method which retrieves parameterized VSD and CRI with the aid of a priori constraints from historical in situ measurements. To run the retrieval, in a python script or an interactive shell, type the following commands:

from boreal import BOREAL_PC

# organise the input optical data
opt_harmonized = BOREAL_PC.harmonize_opt_format(ext, bac, depol)   # ext, bac, depol are dictionaries with keys=wavelength and values=values. e.g., ext={'355': value_355, '532': value_532}

# perform a retrieval
boreal_pc_instance = BOREAL_PC.Retrieval_bimodal(opt_harmonized)
boreal_pc_rtv = boreal_pc_instance.do_retrieval()

# output results in txt format
BOREAL_PC.export_txt(...)

Input arguments for BOREAL_PC.harmonize_opt_format():

• ext: dict, same as that input to BOREAL.inversion(), but the wavelengths have to be '355' and '532'
• bac: dict, same as that input to BOREAL.inversion(), but the wavelengths have to be '355', '532' and '1064'
• depol: dict,same as that input to BOREAL.inversion(), but is mandatory and the wavelengths have to be '355', '532' and '1064'

Note:

1. Since BOREAL-PC is specially designed for dust retrieval, the argument aero_type makes no sense
2. Only the IH model is available.
3. To ensure acceptable retrieval accuracy, the complete optical dataset (i.e., 2a+3b+3d) is required. The accuracy of inverting deficient dataset needs further evaluation.

References

• Chang, Y., Hu, Q., Goloub, P., Veselovskii, I., and Podvin, T.: Retrieval of Aerosol Microphysical Properties from Multi-Wavelength Mie–Raman Lidar Using Maximum Likelihood Estimation: Algorithm, Performance, and Application, Remote Sens., 14, 6208, https://doi.org/10.3390/rs14246208, 2022.
• Chang, Y., Hu, Q., Goloub, P., Podvin, T., Veselovskii, I., Ducos, F., Dubois, G., Saito, M., Lopatin, A., Dubovik, O., and Chen, C.: Retrieval of microphysical properties of dust aerosols from extinction, backscattering and depolarization lidar measurements using various particle scattering models, Atmos. Chem. Phys., 25, 6787–6821, https://doi.org/10.5194/acp-25-6787-2025, 2025.