Metadata-Version: 2.4
Name: taurex-pcq
Version: 1.0
Summary: A TauREx plugin implementing Pre Computed Qext grids for cloud models
Author-email: Maël Voyer <mael.voyer@cea.fr>
License: MIT
Keywords: taurex,exoplanets,retrieval,atmospheres,jwst
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: taurex
Requires-Dist: numba
Requires-Dist: scipy
Requires-Dist: h5py
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Faster clouds for TauREx 3
---

This plugin provides **a new nethod to inclue aerosols** in [TauREx 3](https://github.com/ucl-exoplanets/TauREx3_public), extending the TauREx-PyMieScatt plugin. It significantly speeds up the cloud models by using precomputed extinction efficiency (`Q_ext`) grids. TauREx-PCQ also considerably improves the computation scaling with the number of clouds in the models. The speed-ups for single cloud retrievals are betwwen 1.4 and 2.7. Although, a single-cloud retrieval using Qext grids achieved a speed-up of 1.4, the same retrieval with four clouds became 17 times faster than the corresponding retrieval using direct Mie calculations.
The grids details and validation can be found in Voyer & Changeat (2026), if you use TauREx-PCQ or the grids please cite this paper. The species already available are Mg2SiO4, MgSiO3 (amorph sol-gel and amorph glass), SiO2 (alpha and amorph), SiO, the Titan tholins and water ice. They can be found at: [10.5281/zenodo.17456673](https://doi.org/10.5281/zenodo.17456673) .

For any inquiries, please contact: mael.voyer@u-paris.fr

---

## 🔧 Features

- ✅ Compatible with `transit` and `emmsion` models.
- ✅ Works with any aerosol specie given that the user provides a `.h5` file with :

- A `radius_grid` dataset with the particule sizes in microns ( length `a` ).
- A `wavenumber_grid` dataset with the wavenumber at which the `Q_ext` were computed in cm-1 ( length `b` )
- A `Qext_grid` dataset with the computed `Q_ext` from PyMieScat ( length (`a`, `b`) )

## As an extension of TauREx-PyMieScatt, this pulgin includes the same  capabilities

- ✅ **Supports multiple particle size distributions:**
  - `normal` (log-normal)
  - `budaj` (2015)
  - `deirmendjian` (1964)
- ✅ **Multiple species and per-species fitting**
- ✅ **Particle decay with altitude** (`exp_decay` based on Whitten 2008 / Atreya 2005)
- ✅ **Computes exctinction** using the species optical constant via **Effective Medium Theory (Bohren & Huffman 1983)**
- ✅ **Multiple fittable parameters** for TauREx retrievals

---

## 🔧 Model Parameters

| Name | Description |
|------|-------------|
| `species` | Your name for the species included through the `mie_species_path` parameter. This name will be used as suffixes added to the other parameters to distinguish between included species. |
| `mie_species_path` | Paths to the `Q_ext` grids of the aerosols you want to include |
| `mie_particle_radius_distribution` | `"normal"`, `"budaj"`, or `"deirmendjian"` |
| `mie_particle_mean_radius` | Mean particle radius (µm) |
| `mie_particle_logstd_radius` | Log-normal std dev (for `"normal"` distribution) |
| `mie_particle_paramA/B/C/D` | Parameters for Deirmendjian distribution |
| `mie_particle_mix_ratio` | Number density (molecules/m³) |
| `mie_midP` | Pressure at cloud center (Pa) |
| `mie_rangeP` | Extend of the clouds in log scale around `mie_midP`. If `mie_midP` = 1e5 Pa and `mie_rangeP` = 1 then clouds extend from 1e6 to 1e4 Pa |
| `mie_particle_altitude_distrib` | Currently supports `'exp_decay'` or `'linear'` |
| `mie_particle_altitude_decay` | Decay exponent per species e.g `-5` |

---

## 💡 Usage Example in a TauREx parameter file or 'parfile'

```python
[Model]
model_type = transit

    [[PyMieScattGridExtinction]]

    species = SiO, Mg2SiO4_glass, custom_molecule
    mie_species_path = path_to_SiO.h5 , path_to_Mg2SiO4_glass.h5 , path_to_custom_molecule.h5   #e.g. You can use the optical constant from Kitzmann and Heng 2018
    mie_particle_radius_distribution = budaj
    mie_particle_mean_radius = 0.1, 0.4 , 10
    mie_midP = 1e5, 1e2, 1
    mie_rangeP = 3 , 1 , 2
    mie_particle_mix_ratio = 1e5, 1e8 , 10e3
    mie_particle_radius_Nsampling = 5
    mie_particle_altitude_distrib = linear
```
---
## Limitations

As the `Q_ext` are computed for a range of radii between 1 nm and 30 microns, it is strongly recomended that the `mie_particle_mean_radius` prior does not extend beyond this range. Any radius outside of the range will use the `Q_ext` of the closest radius present in the grid.
