Documentation update

.github/workflows/tests.yaml

@@ -58,14 +58,14 @@ jobs:
           echo $'\n```' >> $GITHUB_STEP_SUMMARY
 
       - name: Make coverage badge
-        if: ${{ github.ref == 'refs/heads/main' && matrix.python-version == '3.10' }}
+        if: ${{ github.ref == 'refs/heads/main' && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }}
         uses: schneegans/dynamic-badges-action@v1.7.0
         with:
           auth: ${{ secrets.GIST_TOKEN }}
           gistID: a25c37a328839edd00bb32d8527aec30
           filename: covbadge.svg
           label: Coverage
           message: ${{ env.total }}%
-          minColorRange: 50
+          minColorRange: 10
           maxColorRange: 90
           valColorRange: ${{ env.total }}

docs/How-to/activity_quantities.md

@@ -1,4 +1,4 @@
-## Rotation and activity quantities (How-to)
+# Find stellar rotation and activity quantities
 
 ### Goal
 Compute high-energy emission quantities (X-ray, EUV, Ly-α) from stellar **mass**, **age**, and **rotation**, optionally add variability/scatter, and (if needed) retrieve a larger set of model diagnostics via `ExtendedQuantities`.
@@ -11,7 +11,8 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**. Luminosities are in **erg s⁻¹** and surface fluxes in **erg s⁻¹ cm⁻²**.
+!!! Units
+    `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**. Luminosities are in **erg s⁻¹** and surface fluxes in **erg s⁻¹ cm⁻²**.
 
 ---
 

docs/How-to/activity_timelines.md

@@ -1,4 +1,4 @@
-## Activity timelines (How-to)
+# Find stellar activity timelines
 
 ### Goal
 Compute how long a star (or a cluster of stars) stays above an activity threshold (e.g., X-ray luminosity) or how long it remains in the saturated regime.
@@ -11,7 +11,8 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** thresholds must match the quantity you use (e.g., `Lx` in **erg s⁻¹**). Ages returned are in **Myr**.
+!!! Units
+    Thresholds must match the quantity you use (e.g., `Lx` in **erg s⁻¹**). Ages returned are in **Myr**.
 
 ---
 

docs/How-to/clusters.md

@@ -1,4 +1,4 @@
-## Cluster evolution calculation (How-to)
+# Calculate cluster evolution
 
 ### Goal
 Compute rotation/activity evolution tracks for a **cluster of stars**, then (a) inspect per-star tracks, (b) evaluate cluster distributions at a given age, and (c) save/reload the cluster to avoid recomputation.
@@ -11,11 +11,12 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**.
+!!! Units
+    `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**.
 
 ---
 
-### Step 1 — Create a cluster from arrays
+### Step 1: Create a cluster from arrays
 
 Create arrays/lists of masses and rotation rates (same length). If `Age` is omitted, MORS interprets `Omega` as the **initial (~1 Myr)** rotation rate.
 
@@ -37,7 +38,7 @@ cluster = mors.Cluster(Mstar=Mstar, Omega=Omega, verbose=True)
 
 ---
 
-### Step 2 — Fit tracks through a specified age (optional)
+### Step 2: Fit tracks through a specified age (optional)
 
 If you provide `Age`, MORS fits tracks so that each star passes through the given rotation rate at that age.
 
@@ -66,7 +67,7 @@ cluster = mors.Cluster(Mstar=Mstar, Omega=Omega, Age=Age)
 
 ---
 
-### Step 3 — Access per-star tracks
+### Step 3: Access per-star tracks
 
 Each star is a `mors.Star` instance stored in `cluster.stars`.
 
@@ -87,7 +88,7 @@ plt.plot(cluster.stars0.AgeTrack, cluster.stars0.LxTrack)
 
 ---
 
-### Step 4 — Get cluster values at a fixed age
+### Step 4: Get cluster values at a fixed age
 
 Use `Values(Age=..., Quantity=...)` to retrieve an array across the cluster:
 
@@ -113,7 +114,7 @@ plt.show()
 
 ---
 
-### Step 5 — Save and reload (recommended for large clusters)
+### Step 5: Save and reload (recommended for large clusters)
 
 Cluster calculations can be expensive for many stars, so saving is recommended.
 
@@ -124,7 +125,7 @@ cluster2 = mors.Load("cluster.pickle")
 
 ---
 
-### Step 6 — Evolve the built-in “model cluster” (optional)
+### Step 6: Evolve the built-in “model cluster” (optional)
 
 MORS includes a composite “model cluster” distribution (derived from observed clusters at ~150 Myr evolved back to 1 Myr). You can load it and evolve it like any other cluster:
 
@@ -135,7 +136,8 @@ Mstar, Omega = mors.ModelCluster()
 cluster = mors.Cluster(Mstar=Mstar, Omega=Omega)
 ```
 
-**Citation note:** If you use this model cluster distribution in research, cite the rotation-measurement sources listed in **Johnstone et al. (2020), Table 1** (150 Myr bin), in addition to the MORS model paper(s).
+!!! Citation
+    If you use this model cluster distribution in research, cite the rotation-measurement sources listed in [Johnstone et al. (2021), Table 1](https://www.aanda.org/articles/aa/pdf/2021/05/aa38407-20.pdf#page=4) (150 Myr bin), in addition to the MORS model paper(s).
 
 ---
 

docs/How-to/distribution_percentile.md

@@ -1,4 +1,4 @@
-# Model distribution and percentiles (How-to)
+# Using model percentiles for initial rotation
 
 ### Goal
 Pick an initial rotation rate from the built-in **model rotation distribution** (Johnstone et al. 2020), inspect a star’s inferred percentile, and convert between **rotation rate and percentile** for a given stellar mass.
@@ -11,7 +11,8 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Omega` is in units of the current solar rotation rate (**Ω☉**). `Prot` is in **days**. `Mstar` is in **M☉**.
+!!! Units
+    `Omega` is in units of the current solar rotation rate (**Ω☉**). `Prot` is in **days**. `Mstar` is in **M☉**.
 
 ---
 

docs/How-to/evolution.md

@@ -1,4 +1,4 @@
-## Evolutionary calculations (How-to)
+# Calculate a star's evolution
 
 ### Goal
 Compute a star’s rotation and activity evolution tracks, then (a) plot a quantity, (b) query values at specific ages, and (c) save the result for reuse.
@@ -11,7 +11,8 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Age` is in **Myr**, `Prot` is in **days**, and `Omega` is in units of the **current solar rotation rate (Ω☉)**.
+!!! Units
+    `Age` is in **Myr**, `Prot` is in **days**, and `Omega` is in units of the **current solar rotation rate (Ω☉)**.
 
 ---
 

docs/How-to/habitablezone.md

@@ -1,4 +1,4 @@
-## 8. Find habitable zone boundaries (How-to)
+# Find habitable zone boundaries
 
 ### Goal
 Compute habitable zone (HZ) boundary orbital distances (AU) as a function of stellar **mass** and **age** using `mors.aOrbHZ`.
@@ -11,9 +11,11 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Mstar` in **M☉**, `Age` in **Myr**, returned distances in **AU**.
+!!! Units
+    **Units:** `Mstar` in **M☉**, `Age` in **Myr**, returned distances in **AU**.
 
-**Citation note:** If you use these HZ boundaries in research, cite **Kopparapu et al. (2013)** (HZ prescription) and **Spada et al. (2013)** (stellar parameters used).
+!!! Citation
+    If you use these HZ boundaries in research, cite [Kopparapu et al. (2013)](../Reference/publications.md#bibliography) (HZ prescription) and [Spada et al. (2013)](../Reference/publications.md#bibliography)(stellar parameters used).
 
 ---
 

docs/How-to/installation.md

@@ -1,5 +1,8 @@
 # Installation 
 
+!!! note
+    The standard way of installing this version of MORS is within the PROTEUS Framework, as described in the [PROTEUS installation guide](https://proteus-framework.org/PROTEUS/installation.html#9-install-submodules-as-editable). 
+
 ### Prerequisites
 - **Python:** >3.11 installed
 - **pip:** available (`python -m pip --version`)
@@ -60,7 +63,7 @@ export FWL_DATA=...
 Where ... should be replaced with the path to your main data directory. To make this permanent on Ubuntu, use
 
 ```console
-gedit ~/.profile
+nano ~/.bashrc
 ```
 
 and add the export command to the bottom of the file.

docs/How-to/set_parameters.md

@@ -1,4 +1,4 @@
-## Setting custom simulation parameters (How-to)
+# Setting custom simulation parameters
 
 ### Goal
 Create simulation parameters for a `Star` (or `Cluster`) run, and optionally restrict the ages saved in output tracks using `AgesOut`.  This overrides MORS default simulation parameters. 

docs/How-to/track_quantities.md

@@ -1,4 +1,4 @@
-## Find stellar quantities using evolution tracks (How-to)
+# Find stellar quantities using evolution tracks
 
 ### Goal
 Find basic stellar evolution properties (radius, luminosity, convective turnover time, moments of inertia, etc.) as a function of **stellar mass** and **age**, using the Spada et al. (2013) tracks bundled with MORS. Optionally, stellar evolution quantities according to the Baraffe model (Baraffe et al., 2002) can be found.
@@ -11,7 +11,8 @@ pip install fwl-mors
 mors download all
 ```
 
-> **Units:** `Mstar` in **M☉**, `Age` in **Myr**. Output units depend on the quantity (listed below).
+!!! Units
+    `Mstar` in **M☉**, `Age` in **Myr**. Output units depend on the quantity (listed below).
 
 ## Spada tracks
 
@@ -130,7 +131,8 @@ If it’s already loaded, this call does nothing.
 
 MORS also provides access to Baraffe et al. (2002) tracks, which use **different units** than the Spada helpers above.
 
-> **Baraffe units:** `Mstar` in **M☉** (valid range: ~0.01–1.4), `time` in **years (yr)**.
+!!! Units
+    `Mstar` in **M☉** (valid range: ~0.01–1.4), `time` in **years (yr)**.
 
 ### Step 1. Load a Baraffe track (with interpolation)
 ```python

docs/Reference/publications.md

@@ -0,0 +1,15 @@
+# Publications and bibliography
+
+## MORS publications
+
+- Johnstone, C. P., Bartel, M., & Güdel, M. (2021). The active lives of stars: A complete description of the rotation and XUV evolution of F, G, K, and M dwarfs. *Astronomy & Astrophysics*, 649, A96. [https://doi.org/10.1051/0004-6361/202038407](https://doi.org/10.1051/0004-6361/202038407)
+
+Additionally, MORS is part of all publications of the PROTEUS Framework, which can be found [here](https://scixplorer.org/public-libraries/EVAJ1UgWTCy2Z7TRoSmjtQ). 
+
+## Bibliography
+
+- Spada, F., Demarque, P., Kim, Y. C., & Sills, A. (2013). The radius discrepancy in low-mass stars: single versus binaries. *The Astrophysical Journal*, 776(2), 87. [https://doi.org/10.1088/0004-637X/776/2/87](https://doi.org/10.1088/0004-637X/776/2/87)
+
+- Kopparapu, R. K., Ramirez, R., Kasting, J. F., Eymet, V., Robinson, T. D., Mahadevan, S., ... & Deshpande, R. (2013). Habitable zones around main-sequence stars: new estimates. *The Astrophysical Journal*, 765(2), 131. [https://doi.org/10.1088/0004-637X/765/2/131](https://doi.org/10.1088/0004-637X/765/2/131)
+
+- Baraffe, I., Chabrier, G., Allard, F., & Hauschildt, P. H. (2002). Evolutionary models for low-mass stars and brown dwarfs: Uncertainties and limits at very young ages. *Astronomy & Astrophysics*, 382(2), 563-572. [https://doi.org/10.1051/0004-6361:20011638](https://doi.org/10.1051/0004-6361:20011638)

docs/Tutorials/first_run.md

@@ -10,11 +10,12 @@ By the end of this tutorial you will:
 5. Find stellar values at specific ages
 6. Save and reload the result
 
-> **Time/units cheat sheet:** `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**.
+!!! Units
+    `Mstar` in **M☉**, `Age` in **Myr**, `Prot` in **days**, `Omega` in **Ω☉**.
 
 ---
 
-## 0) Prerequisites
+## 0. Prerequisites
 You need:
 
 - Python 3 environment with `pip`
@@ -34,7 +35,7 @@ source .venv/bin/activate
 
 ---
 
-## 1) Install MORS
+## 1. Install MORS
 ```bash
 pip install fwl-mors
 ```
@@ -46,7 +47,7 @@ python -c "import mors; print('mors imported:', mors.__version__ if hasattr(mors
 
 ---
 
-## 2) Download stellar evolution data
+## 2. Download stellar evolution data
 MORS requires stellar evolution tracks (downloaded once):
 ```bash
 mors download all
@@ -64,7 +65,7 @@ export FWL_DATA=/path/to/your/data
 
 ---
 
-## 3) Create your first star
+## 3. Create your first star
 Create a 1 M☉ star with an initial rotation period of 2.7 days (at ~1 Myr):
 ```python
 import mors
@@ -78,7 +79,7 @@ star = mors.Star(Mstar=1.0, Omega=10.0)
 
 ---
 
-## 4) Inspect what tracks exist
+## 4. Inspect what tracks exist
 Print track names and units:
 ```python
 star.PrintAvailableTracks()
@@ -98,7 +99,7 @@ lx  = star.LxTrack
 
 ---
 
-## 5) Plot a track
+## 5. Plot a track
 ```python
 import matplotlib.pyplot as plt
 
@@ -112,7 +113,7 @@ If you see a plot and no errors, your installation + data are working.
 
 ---
 
-## 6) Find stellar values at specific ages
+## 6. Find stellar values at specific ages
 Use the generic accessor:
 ```python
 print(star.Value(Age=150.0, Quantity="Lx"))
@@ -125,7 +126,7 @@ print(star.Lx(150.0))
 
 ---
 
-## 7) (Optional) Try percentiles: slow/medium/fast rotators
+## 7. (Optional) Try percentiles: slow/medium/fast rotators
 This uses the built-in model distribution:
 ```python
 slow   = mors.Star(Mstar=1.0, percentile="slow")    # 5th percentile
@@ -138,7 +139,7 @@ print("fast percentile:", fast.percentile)
 
 ---
 
-## 8) Save and reload (recommended)
+## 8. Save and reload (recommended)
 Save:
 ```python
 star.Save(filename="star.pickle")

docs/contact.md

@@ -0,0 +1,9 @@
+# Contact
+
+We encourage you to reach out! Choose the most appropriate channel below.
+
+| Channel | Use for |
+|---------|---------|
+| [Forming Worlds Discussions](https://github.com/orgs/FormingWorlds/discussions) | Questions, installation help, feature suggestions |
+| [GitHub Issues](https://github.com/FormingWorlds/MORS/issues) | Bug reports, specific feature requests |
+| [proteus_dev@formingworlds.space](mailto:proteus_dev@formingworlds.space) | General enquiries |