Metadata-Version: 2.4
Name: spinor
Version: 0.1.0.dev0
Summary: Add your description here
Author: Giuseppe Sorrentino
Author-email: Giuseppe Sorrentino <166509923+giusesorrentino@users.noreply.github.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Software Development :: Libraries
Classifier: Operating System :: OS Independent
Requires-Dist: matplotlib>=3.11.2
Requires-Dist: numpy>=2.5.3
Requires-Dist: scipy>=1.18.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# twirl

[**twirl** (formerly SpyDust)](https://arxiv.org/abs/2412.03431) is a Python package for modeling spinning dust radiation in astrophysical environments. Building upon the IDL [**SPDUST**](https://arxiv.org/pdf/1003.4732), it offers enhanced capabilities and corrections for astrophysical research.

For details on the underlying model, see [SpyDust: an improved and extended implementation for modeling spinning dust radiation](https://arxiv.org/abs/2412.03431).

## Features

- Grain-shape modeling, rotational dynamics, and directional radiation.
- Updated treatments of electric-dipole radiation back-reaction and plasma drag.
- Parallel execution using MPI.
- The retained legacy model at `twirl.legacy.spdust_as_is`.

## Package layout

- `twirl.physics`: grain properties and physical processes.
- `twirl.model`: spinning-dust calculations and SED generation.
- `twirl.analysis`: SED fitting, moment expansion, and Stokes analysis.
- `twirl.core`: shared numerical and parallel-computing utilities.
- `twirl.legacy.spdust_as_is`: the legacy implementation retained for comparison.
- `twirl.data`: bundled tables, grouped by physical process.

## Requirements

The project requires Python 3.12 or newer. Its declared dependencies are NumPy,
SciPy, and Matplotlib. MPI support uses `mpi4py`; free-free emission also uses
Pandas.

## Installation

Install the project with pip:

```bash
pip install .
```

Or clone this repository and install its dependencies in your environment.

## Usage

The following example computes a spectrum for a sample CNM environment:

```python
from twirl.model.spinning_dust import SpyDust

cnm_params = {
    "nh": 30,
    "T": 100.0,
    "Chi": 1,
    "xh": 1.2e-3,
    "xC": 3e-4,
    "y": 0,
    "gamma": 0,
    "dipole": 9.3,
    "line": 7,
}

spectrum = SpyDust(
    cnm_params,
    min_freq=1,
    max_freq=400,
    n_freq=200,
    single_beta=True,
)
```

The individual physics, model, and analysis modules can also be imported
directly from their corresponding packages.

## Bundled data

Reference tables and generated lookup tables are stored under
`src/twirl/data/`, separated into `charge/`, `collisions/`, `free_free/`,
`grains/`, `infrared/`, and `plasma/`.

## Resources

- [SpyDust paper](https://arxiv.org/abs/2412.03431)
- [SPDUST documentation](https://cosmo.nyu.edu/yacine/spdust/spdust.html)
- [SpyDust GitHub collaboration](https://github.com/SpyDust/SpyDust)
