# SpyDust

[**SpyDust**](https://arxiv.org/abs/2412.03431) is an advanced Python package for modeling spinning dust radiation in astrophysical environments. Building upon previous models (the IDL [**SPDUST**](https://arxiv.org/pdf/1003.4732)), SpyDust offers enhanced capabilities and corrections, making it a valuable tool for researchers in astrophysics and related fields.

For a detailed understanding of the underlying models and theoretical background, refer to the publication: [SpyDust: an improved and extended implementation for modeling spinning dust radiation](https://arxiv.org/abs/2412.03431).

---

## Features

- **Comprehensive Grain Shape Modeling**: Considers a wide range of grain geometries, providing corresponding grain dynamics, directional radiation fields, and angular momentum transports.

- **Updated Physical Processes**: Incorporates corrections and extensions, including updated expressions for the effects of electrical dipole radiation back-reaction and plasma drag on angular momentum dissipation.

- **Parallisation**: Functions can be run in parallel (implemented by mpi4py) by simply setting the corresponding keyword to True.

- **SPDUST as is** mode: Provides a submodule, **SPDUST_as_is**, which is exactly the full equivalent of the IDL spdust. Just in case the user wants to stick with the spdust simulation.

- **Example notebooks**: Provide some Jupyter notebooks to help users get started with this package.

---

## Requirements

SpyDust requires Python 3.7 or higher (up to Python 3.9) and the following dependencies:

**Required**:
- `numpy`
- `scipy`
- `mpi4py`

**Optional**:
- `pandas`: This is not needed for spinning dust spectra, but if free free emission is also desired (using free_free.py), then it is needed.

---

## Installation

You can install SpyDust using pip:

```bash
pip install SpyDust --no-deps
```

Otherwise, you can directly `git clone' this repo and set up the environment by yourself.

---

# Usage

Import the package in your project and explore its functionalities for modeling spinning dust radiation. Data files required for computations are bundled with the package.

---

## Example usage:

Here is an example of using the `SpyDust.SpyDust' function to generate a spectrum for a sample CNM environment:
```python
from SpyDust.SpyDust import SpyDust

# Define the environment:
# 'nH': total hydrogen number density (cm3),
# 'T': gas temperature (K),
# 'chi': intensity of the radiation field relative to the average interstellar radiation field,
# 'xh': hydrogen ionization fraction,
# 'xC': ionized carbon fractional abundance,
# 'y': molecular hydrogen fractional abundance,
# 'gamma': H2 formation efficiency,
# 'dipole': rms dipole moment for dust grains.
CNM_params = {'nh' : 30, 'T': 100., 'Chi': 1, 'xh': 1.2e-3, 'xC': 3e-4, 'y' : 0, 'gamma': 0, 'dipole': 9.3, 'line':7}


# Generate the spectrum
spectrum = SpyDust(params, min_freq=1, max_freq=400, n_freq=200, single_beta=True)

# Plot the spectrum
import matplotlib.pyplot as plt
plt.loglog(spectrum[0,:], spectrum[1,:])
plt.xlabel('Frequency (GHz)')
plt.ylabel('Emissivity')
plt.show()
```

Instead of using the SpyDust rotation distribution method described in the paper, you can generate spectra using your own arbitrary distributions of configuration parameters as inputs to the `SpyDust.SED' function.

--- 

## History

- **Version 1.3**: Added new modules to SpyDust, including "mom_exp.py", "SED_fit.py", "full_Stokes.py", and notebooks and products for the spectral feature paper 

- **Version 1.2**: Fixed import bugs in the example notebooks.  

- **Version 1.1**: Numba dependency removed and installation issues fixed. 

- **Version 1.0**: Initial release of SpyDust, introducing comprehensive grain shape modeling, updated physical processes, and degeneracy analysis tools.




## TODO (Future Versions)
- Future upgrades will include features such as the SED fitting tool (based on perturbation statistics tools like moment expansion) and improve the treatment of the grain rotation distribution.

---

## Resources

- **Author**: Zheng Zhang
- **License**: This project is licensed under the MIT License - see the LICENSE file for details.
- **Collaboration**: [SpyDust GitHub Collaboration](https://github.com/SpyDust/SpyDust)
- **Spdust Documentation**: We refer users to the website of [spdust](https://cosmo.nyu.edu/yacine/spdust/spdust.html) for better documentation of environmental parameters 

---


