Metadata-Version: 2.4
Name: boreal_LOA
Version: 0.5.2
Summary: Python package of the Basic algOrithm for REtrieval of Aerosol with Lidar - an algorithm to retrieve aerosol optical and microphysical properties from lidar measurements
Author-email: Yuyang Chang <yuyang.chang@univ-lille.fr>
License-Expression: LicenseRef-BSD-3-Clause-with-Citation-Requirement
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy==1.23.5
Requires-Dist: scipy==1.13.1
Requires-Dist: pandas==2.3.3
Requires-Dist: matplotlib==3.6.2
Dynamic: license-file

# BOREAL package for aerosol microphysical property retrieval from lidar measurements
## General description 
The **BOREAL** (**B**asic alg**O**rithm for **RE**trieval of **A**erosol with **L**idar) 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
```bash
# 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
```bash
python3 -m pip install -r requirements.txt
```
2. Alternatively, you can install the package from PyPI. In the objective directory, type
```bash
python3 -m pip install boreal-LOA
```

### General routine to perform an inversion and derive the retrieval results
```python
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   | -                 |

