boreal-LOA 0.5.2

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 for aerosol microphysical property retrieval from lidar measurements

General description

The BOREAL (Basic algOrithm for REtrieval of Aerosol with Lidar) algorithm is developed by the Laboratoire d'Optique Atmosphérique, 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 Citation and acknowledge the contribution of "University of Lille/CNRS/Laboratoire d'Optique Atmosphérique". 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.

Citation

If you use this software in your work, please cite the software as

Chang. (2026). BOREAL package for aerosol microphysical property retrieval from lidar measurements (v0.5.0). Zenodo. https://doi.org/10.5281/zenodo.18664803

and the ones of the following publications related to your work:

• BOREAL algorithmic concept and implementation

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.

• Extend BOREAL to non-spherical particle retrieval

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.

• BOREAL-PC (Parameterized Constrained) algorithm for dust retrieval

Chang, Y., Hu, Q., Goloub, P., and Podvin, T.: Improved Dust Microphysical Retrieval From LiDAR by Introducing a Priori Constraints From In Situ and Laboratory Measurements, JGR Atmospheres, 131, e2025JD045677, https://doi.org/10.1029/2025JD045677, 2026.

Acknowledgments

The scattering properties of irregular particles are obtained from the TAMUdust2020 database (https://zenodo.org/record/4711247) with reference: Saito, M., P. Yang, J. Ding, and X. Liu (2021), A comprehensive database of the optical properties of irregular aerosol particles for radiative transfer simulations, J. Atmos. Sci., 78, 2089–2111. The scattering properties of spherical and spheroidal particles are obtained from the GRASP Spheroid-package (https://www.grasp-open.com/products/spheroid-package-release/) with the reference: Dubovik, O., A. Sinyuk, T.Lapyonok, B. Holben, M. Mishchenko, P. Yang, T. Eck, H. Volten, O. Munoz, B. Veihelmann, W. van der Zande, J.-F. Leon, M. Sorokin, I. Slutsker (2006), Application of spheroid models to account for aerosol particle nonsphericity in remote sensing of desert dust, J. Geophys. Res., 111, D11208, doi:10.1029/2005JD006619.

License

This project is licensed under the BSD-3-Clause with extra terms (see LICENSE.txt attached with the project).

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 and utilisation

The package is developed with Python.

Set up a Python 3.9+ environment

# in shell, go to the objective directory then type
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip 

There are two ways to install the package.

1. You can download the .tar.gz file from https://pypi.org/project/boreal-LOA/#files, or https://github.com/GitRichard-loa/boreal-LOA.git, unarchive the file and copy all the contents in the root directory to the objective directory where the python environment has been set, then in the objective directory, type

python3 -m pip install -r requirements.txt

2. Alternatively, you can install the package from PyPI. In the objective directory, type

python3 -m pip install boreal-LOA

General routine to perform an inversion and derive the retrieval results

from boreal import BOREAL, BOREAL_PC

# perform inversion with BOREAL
retrieval = BOREAL.inversion(...)

# alternatively, perform inversion with BOREAL_PC
boreal_pc_instance = BOREAL_PC.Retrieval_bimodal(...)
retrieval = boreal_pc_instance.do_retrieval(...)

# you may visualize the retrieved parameters and optical fitting by
from boreal import retrieval_process

filepath_rtv = retrieval_process.plot_rtv_and_fit(...)

# or export everything to a txt file
filepath_borealpc_txt = retrieval_process.export_txt(...)

# for more instructions, please refer to "runBOREAL.py" and the "reference_output" under "run_example" (note: this folder is not included on PyPI and is only available on GitHub).

Notes of calling BOREAL.inversion()

Mandatory arguments:

• 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', 'absorbing', or 'non-absorbing', 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

Notes of calling BOREAL_PC

1. Since BOREAL-PC is specially designed for dust retrieval, there is no need to specify aero_type
2. Only the IH model is available, there is no need to specify model.
3. The complete 3b+2a+3d dataset is favorable to obtain the quality-assured retrieval. Deficient dataset with number of input measurements less than 8 is invertible in principle, but its accuracy is not guaranteed. Dataset with number of input measurements less than 6 is not allowed due to the underdetermination.

Output parameters

• related to particle size

Parameter	Full name	Unit
VSD	Particle volume size distribution	${\mu}m^3*cm^{-3}$
$V_t$	Total volume concentration	${\mu}m^3*cm^{-3}$
$R_{eff}$	Effective radius	${\mu}m$
$R_c$	Coarse-mode median radius*	${\mu}m$
$S_c$	Coarse-mode geometric standard deviation*	${\mu}m$
$\eta_f$	Fine-mode volume fraction*	-
* parameter only output by BOREAL-PC

• functions of wavelength (355, 532, 1064 nm)

Parameter	Full name	Unit
$m_R$	Real part of the refractive index	-
$m_I$	Imaginary part of the refractive index	-
SSA	Single-scattering albedo	-
$\alpha$	Extinction coefficient	$Mm^{-1}$
$\beta$	Backscattering coefficient	$Mm^{-1}*sr^{-1}$
LR	Lidar ratio	sr
$\delta$ or PLDR	Particle linear depolarization ratio	-