Metadata-Version: 2.4
Name: MANTA_Ray_optics
Version: 2.0.0
Summary: MANTA-Ray (Modified Absorption of Non-spherical Tiny Aggregates in the Rayleigh regime) is a model that calculates the absorption efficiency and absorption cross-section of fractal aggregates.
Project-URL: Homepage, https://github.com/mglodge/MANTA-Ray/
Author-email: Matt Lodge <matthew.g.lodge@gmail.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.0.1
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

![MANTA Ray logo final](https://github.com/user-attachments/assets/daace825-8432-44ba-a673-0f6d441a3116)

MANTA-Ray (<ins>**M**</ins>odified <ins>**A**</ins>bsorption of <ins>**N**</ins>on-spherical <ins>**T**</ins>iny <ins>**A**</ins>ggregates in the <ins>**Ray**</ins>leigh regime) is a model that calculates the absorption efficiency and absorption cross-section of fractal aggregates. It is a very powerful and fast tool that can be used to estimate the amount of absorption that occurs in dust and haze particles of any shape, provided that the electromagnetic radiation is in the Rayleigh regime (see below for strict definition), often in the context of planetary atmospheres or protoplanetary disks. It obtains values within 10-20% of those calculated by a rigorous benchmark model (the discrete dipole approximation), but is $10^{13}$ times faster. It is provided here as two python functions. For full details of the methodology, or if the code is useful in your project, please cite the paper below:

  "MANTA-Ray: Supercharging Speeds for Calculating the Optical Properties of Fractal Aggregates in the Long-Wavelength Limit" (2024), Lodge, M.G., Wakeford H.R., and Leinhardt, Z.M.

# Getting started

The easiest way to run MANTA-Ray is to install it into your python environment using pip:

	pip install MANTA_Ray_optics

Then import the functions into your python code and try an example calulation **(IMPORTANT: Note the use of underscores _ instead of hyphens - for importing the module, as suggested by the python PEP 8 style guide)**:

	# import the module
  	from MANTA_Ray_optics import MANTA_Ray

 	# set the input variables
 	wavelength = 100   # in um
 	radius = 0.5   # in um
	d_f = 1.8		
 	n = 3
	k = 0.5

	# calculate Q_abs
	Q_abs = MANTA_Ray.find_Q_abs(wavelength, radius, d_f, n, k)
 
	print(Q_abs)
 
If MANTA-Ray installed correctly, you should see the value:

	0.021153387751343056 

The inputs to the functions are:

1) wavelength: the wavelength ($\lambda$) of the electromagnetic radiation (in μm).
2) radius: the particle radius ($R$) (in μm) -- see note below*.
3) d_f: the fractal dimension ($d_f$) of the aggregate. The code has been tested for values between $d_f=$ 1.2 (linear) and 2.7 (compact). See section "The Model" below for more details.
4) n: the real component of refractive index
5) k: the imaginary component of refractive index

*Because the aggregates are non-spherical, they do not have a radius. To represent the physical size of the particle, we use the radius of a <i>sphere that has exactly the same volume</i> as the fractal aggregate (i.e. the radius if the aggregate material was squashed/compacted into a sphere). 

The example above determines the absorption efficiency of an aggregate of fractal dimension 1.8, with a radius of 0.5 μm, at a wavelength of 100 μm, and assuming a material refractive index $m=n+k$ i = 3 + 0.5 i. Note that to be in the Rayleigh regime, and for this theory to work, it is assumed that $\lambda \geq 100R$, and the code will return an error message (and not proceed) if this condition is not met.

To use the functions, just provide the above inputs, strictly in that order. There are two functions in this package:

1) find_Q_abs: calculates absorption efficiency $Q_{abs,MR}$ (Eq. 5 in Lodge et al. 2024)
2) find_C_abs: calculates absorption cross-section (where $C_{abs}=Q_{abs} \pi R^2$)

Both functions use the same input variables:

	Q_abs = MANTA_Ray.find_Q_abs(wavelength, radius, d_f, n, k)
	C_abs = MANTA_Ray.find_C_abs(wavelength, radius, d_f, n, k)

If a pip install fails (or simply if you prefer), you could copy and paste the functions from MANTA_Ray.py directly into your code and use them as regular functions instead.

# The Model

This section provides a brief overview of the model, but for a full explanation and more details, please read Lodge et al. 2024. 

Transmission Electron Microscope (TEM) images of solid matter in Earth's atmosphere shows that they often form very complex shapes, which we call fractal aggregates. Their exact shape depends on the material and conditions under which they form. Typically, we characterise them by a single number -- their fractal dimension $d_f$:

<p align="center">
  <img src="https://github.com/user-attachments/assets/7060caea-1465-45dd-9f64-74a351b0733b" alt="drawing" width="400" />
</p>

In the image above the two aggregates are both composed of 24 "monomers" (individual spheres), but in different arrangements. These shapes are characterised in many optical models by $d_f$ which is a number between 1 (representing a straight line) and 3 (compact and perfectly spherical).

Modelling the optical properties of complex shapes is difficult, and Mie theory is often used (which assumes that the particles are spherical). However, this can often be a significant underestimate of the amount of absorption (by factors of up to 1,000 -- see Lodge et al. 2024). Calculating the optical properties for the true aggregate shape can be done using a rigorous code such as the discrete dipole approximation (DDA -- Draine and Flatau, 1994), but this is usually incredibly time consuming (and unfeasible for use in forward models that wish to study many wavelengths/particle sizes). In contrast, MANTA-Ray estimates absorption cross-sections with average accuracies of 10-20% compared to DDA, but $10^{13}$ times faster. It works for any wavelength, particle size, and refractive index $m$ within 1+0.01i< $m$ <11+11i. It is strictly only for use in the Rayleigh Regime (where the wavelength $\lambda$ is significantly larger than the radius $R$ of a sphere of equivalent volume to the aggregate -- here we define this regime as $\lambda \geq 100R$).

The MANTA-Ray model uses the following equation to determine the absorption efficiency $Q_\mathrm{abs}$:

$Q_\mathrm{ext} = \chi \frac{8 \pi R}{\lambda} \mathrm{Im} \left(\frac{m^2 - 1}{m^2 + 1} \right)$

Where the modification factor $\chi$ is given by:

$\chi = a_0 + a_1 n +a_2 k + a_3 n^2 + a_4 nk + a_5 k^2$

And the coefficients $a_0$ - $a_5$, are calculated using the methodology in Lodge et al. (2024).

# Lookup table functionality

In MANTA-Ray v2.0, we provide functionality to interpolate between and extrapolate from the original DDA dataset using a thin plate spine within the RBF interpolator of SciPy. This allows users to estimate DDA results from the dataset that was used to build MANTA-Ray, in a more precise way than using the quadratic function from the regular model, for cases where extreme accuracy is important. Users can choose a different value for d_f, n, and k, and the code will interpolate using the dataset below to find X rather than using the quadratic model from the paper (see above). To use this functionality, simply add the variable `lookup=True` to the function call, e.g.:

	Q_abs = MANTA_Ray.find_Q_abs(wavelength, radius, d_f, n, k, lookup=True)
	C_abs = MANTA_Ray.find_C_abs(wavelength, radius, d_f, n, k, lookup=True)

<p align="center">
  <img src="https://github.com/user-attachments/assets/04b43f78-aacd-4f76-9ced-c6727d257295" alt="drawing" width="500" />
</p>

The default value for this parameter is `lookup=False`, which reverts to using the quadratic model from Lodge et al. (2024).
