Metadata-Version: 2.4
Name: fwl-mors
Version: 26.7.12
Summary: Stellar rotation and activity evolution model
Author-email: "Colin P. Johnstone" <colinjohnstone@gmail.com>, Harrison Nicholls <contact@h-nicholls.space>, Laurent Soucasse <l.soucasse@esciencecenter.nl>, Tim Lichtenberg <tim.lichtenberg@rug.nl>, Karen Stuitje <stuitje@proton.me>
License: MIT License
Project-URL: homepage, https://github.com/FormingWorlds/MORS
Keywords: exoplanet,stellar evolution
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: click
Requires-Dist: matplotlib
Requires-Dist: numpy>=2.0.0
Requires-Dist: osfclient
Requires-Dist: platformdirs
Requires-Dist: scipy
Requires-Dist: zenodo_get
Provides-Extra: develop
Requires-Dist: coverage[toml]; extra == "develop"
Requires-Dist: pip-tools; extra == "develop"
Requires-Dist: pytest; extra == "develop"
Requires-Dist: pytest-cov; extra == "develop"
Requires-Dist: pytest-timeout; extra == "develop"
Requires-Dist: ruff; extra == "develop"
Requires-Dist: tomlkit; extra == "develop"
Provides-Extra: docs
Requires-Dist: zensical==0.0.39; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: markdown-include; extra == "docs"
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Provides-Extra: publishing
Requires-Dist: twine; extra == "publishing"
Requires-Dist: wheel; extra == "publishing"
Requires-Dist: build; extra == "publishing"
Dynamic: license-file

# MORS

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/github/actions/workflow/status/FormingWorlds/MORS/docs.yaml?branch=main&label=Docs)](https://proteus-framework.org/MORS/)
[![codecov](https://img.shields.io/codecov/c/github/FormingWorlds/MORS/main?label=coverage&logo=codecov)](https://app.codecov.io/gh/FormingWorlds/MORS)
[![Unit Tests](https://img.shields.io/github/actions/workflow/status/FormingWorlds/MORS/tests.yaml?branch=main&label=Unit%20Tests)](https://github.com/FormingWorlds/MORS/actions/workflows/tests.yaml)
[![Integration Tests](https://img.shields.io/github/actions/workflow/status/FormingWorlds/MORS/nightly.yml?branch=main&label=Integration%20Tests)](https://github.com/FormingWorlds/MORS/actions/workflows/nightly.yml)

**MORS** (Model for Rotation of Stars) is the stellar-evolution module of the [PROTEUS](https://proteus-framework.org/PROTEUS) coupled atmosphere-interior evolution framework. It models the rotational spin-down and high-energy (X-ray, EUV, Lyman-α) emission of low-mass stars over their lifetimes, following the rotation-activity model of [Johnstone, Bartel & Güdel (2021)](https://www.aanda.org/articles/aa/abs/2021/05/aa38407-20/aa38407-20.html).

Given a stellar mass and an initial rotation rate, or an observed rotation percentile, MORS returns the time evolution of the rotation period, the X-ray, EUV and Lyman-α luminosities, and the bolometric luminosity, radius and effective temperature interpolated from stellar-structure tracks. Within PROTEUS it supplies the stellar XUV history that drives atmospheric escape and photochemistry.

## Model

MORS evolves the surface rotation of a low-mass star (0.1-1.25 Msun) with a wind-braking spin-down law calibrated to the rotation distributions of open clusters, then maps rotation to activity through the Rossby-number rotation-activity relation: X-ray luminosity first, then EUV and Lyman-α from empirical band scalings. Structural quantities (bolometric luminosity, radius, effective temperature) are interpolated from [Spada et al. (2013)](https://iopscience.iop.org/article/10.1088/0004-637X/776/2/87/meta) evolutionary tracks by default; Baraffe et al. (2015) tracks (0.01-1.40 Msun, no rotation model) are available as an alternative.

## Documentation

Full documentation is at **[proteus-framework.org/MORS](https://proteus-framework.org/MORS/)**, including:

- [Getting started](https://proteus-framework.org/MORS/getting_started.html): installation and a quick path to a first run.
- [Tutorial](https://proteus-framework.org/MORS/Tutorials/first_run.html): a first stellar-evolution run and how to read its output.
- [How-to guides](https://proteus-framework.org/MORS/How-to/installation.html): install, evolve a star, read tracks and activity quantities, compute habitable-zone boundaries, run the tests.
- [Explanations](https://proteus-framework.org/MORS/Explanations/rotation.html): rotation model, X-ray and EUV activity, stellar structure, spectral synthesis, and coupling to PROTEUS.
- [API reference](https://proteus-framework.org/MORS/Reference/api/index.html) and [validation anchors](https://proteus-framework.org/MORS/Validation/physicalmodel.html): every public function with NumPy-style docstrings, plus the per-source reference-pinned test inventory.

## Installation

```console
pip install fwl-mors
```

Or, for development:

```console
git clone https://github.com/FormingWorlds/MORS.git
cd MORS
pip install -e .[develop,docs]
```

The `docs` extra pulls in [Zensical](https://zensical.org/) so you can build this documentation locally with `zensical serve`.

### Stellar evolution data

MORS ships without the stellar-evolution tracks, which live in the [OSF repository](https://osf.io/9u3fb/). Set the `FWL_DATA` environment variable to the directory where the data should live, then download the tracks:

```console
export FWL_DATA=/your/local/path/FWL_DATA   # add to ~/.bashrc to persist
mors download all
```

## Quick start

```python
import mors

star = mors.Star(Mstar=1.0, Prot=2.7)  # 1 Msun, initial rotation period at 1 Myr
print(star.Lx(150.0))                  # X-ray luminosity at 150 Myr [erg s-1]
```

See the [first-run tutorial](https://proteus-framework.org/MORS/Tutorials/first_run.html) for the full walkthrough.

## Citation

If you use MORS in published work, please cite:

- [Johnstone, Bartel & Güdel (2021)](https://www.aanda.org/articles/aa/abs/2021/05/aa38407-20/aa38407-20.html), *A&A*, 649, A96 (rotation and XUV evolution model)
- [Spada et al. (2013)](https://iopscience.iop.org/article/10.1088/0004-637X/776/2/87/meta), *ApJ*, 776, 87 (stellar evolution tracks)

If you use the model cluster distribution or percentiles, also cite the rotation-measurement sources in Table 1 of Johnstone et al. (2021).

## License

[MIT License](LICENSE.md). MORS is part of the [PROTEUS framework](https://proteus-framework.org/).
