R5Tools - a Python toolkit for the scale radius R_5 (equivalent to R_-2) of stellar systems, with conversions to other scales, projected (2D) and enclosed (3D) light fractions, and dynamical mass estimators

R5Tools is a Python companion package for Graham (2026), providing fast, accurate, and numerically robust calculations associated with the projected scale radius R_5 (a.k.a. R_-2) of the Sersic R^(1/n) profile:

$$R_5 \equiv R_{-2} = R_{\rm e} \left( \frac{2n}{b_n} \right)^n$$

where b_n is defined by the Sersic half-light condition:

$$\gamma(2n, b_n) = \frac{1}{2} \Gamma(2n)$$

This toolkit calculates Sersic structural parameters, projected and three-dimensional light fractions, the refined r_-3 scale, the M_-3 dynamical mass estimator, the spatial mass-to-light ratio (M_dyn/L)_-3, and aperture-dependent mass-follows-light virial coefficients K_V.

---

Interactive Web Interface

A browser-based version of the calculator is available at:

https://r5tools.streamlit.app/

(This provides an interactive front-end; the authoritative, citable source remains the Python package on Zenodo and GitHub.)

---

Features

• Exact b_n Solver: Evaluates Capaccioli's b_n to machine precision using native inverse regularized incomplete gamma functions.
• b_n-Free Conversions: Maps R_5 exactly to traditional disc scale lengths (e.g., R_5 = 2h for an exponential disc) and non-parametric apertures (e.g., R_1(infinity) = R_5 for n=1).
• Exact g(n) Solver: Numerically solves for the exact anisotropy-insensitive spatial radius ratio r_-3/R_5 using Brent's method on the deprojected density profile.
• Singularity-Free Deprojection: Computes the exact 3D enclosed light fraction (F_3D) using the single-integral deprojection identity of Graham (2026). The coordinate substitution R = r cosh(u) is implemented to analytically remove the square-root endpoint singularity.
• Refined Wolf-Type Dynamical Estimators: Computes the n-dependent enclosed mass M_-3 and spatial mass-to-light ratio (M_dyn/L)_-3, correcting standard half-light mass biases via Q(n) = (M_dyn/L)_-3 / (M_dyn/L)_1/2.
• Aperture-Dependent Virial Coefficients: Computes K_V(n, 0.1 R_e) for central apertures (valid across 0.5 <= n <= 10), the gravitational radius ratio R_g/R_5, and the infinite-aperture limit K_V(n, infinity) = 3 R_g/R_5.
• Flexible Photometric Input: Accepts radii in parsecs, kiloparsecs, or arcseconds, and allows the user to supply either surface brightness (mu) or total apparent magnitude (m_tot).
• Major-axis / Circularised Handling: Automatically converts major-axis radii to circularised (geometric-mean) radii using the axis ratio b/a, and reports both sets of scales.
• Observer-Oriented CLI & API: Supports programmatic Python imports as well as an interactive, unit-aware terminal interface.

---

Requirements

For Core Library & CLI:

• Python >= 3.8
• numpy
• scipy

(Note: streamlit is not required to use R5Tools in Python scripts or via the terminal interface. It is only needed if you wish to run the web interface locally).

---

Installation

Option 1: Package Install (Recommended)

git clone https://github.com/A-Graham/R5Tools.git
cd R5Tools

# Optional: create & activate a virtual environment
python3 -m venv r5env
source r5env/bin/activate      # Linux / macOS
# r5env\Scripts\activate       # Windows

pip install -e .

Option 2: Direct Script Use (Without Installing)

If you prefer to run the standalone script directly without installing it as a package:

# Ensure dependencies are present
python3 -m pip install numpy scipy

# Run directly
python3 R5Tools.py

---

Quick Start (Python API)

You can import and use R5Tools directly in your Python scripts:

import R5Tools as r5

n = 4.0
print(f"R_5 / R_e:               {r5.get_R5_over_Re(n):.4f}")
print(f"r_-3 / R_5 (g_approx):   {r5.get_g_approx(n):.4f}")
print(f"3D light inside r = R_5: {r5.get_F3D(r5.get_R5_over_Re(n), n):.2%}")

Interactive Command-Line Interface

To run the interactive, unit-aware terminal tool:

r5tools

(or python3 R5Tools.py)

Optional: Interactive Web Interface

A browser-based version of the calculator is available at:

https://r5tools.streamlit.app/

(This is a convenient front-end; the authoritative, citable source remains the Python package on Zenodo.)

If you wish to host the web calculator locally on your own machine:

pip install streamlit
streamlit run app.py

---

Troubleshooting

• ModuleNotFoundError: No module named 'numpy' (or 'scipy'):
  Ensure your active Python environment has NumPy and SciPy installed (pip install numpy scipy).
• Compatibility:
  Works on Linux, macOS, and Windows with Python $\ge 3.8$.

Mathematical Basis

The equations implemented in this program are described in:

• Graham, A. W. (2026), "R_e, or not R_e: Developing $R_5\equiv R_{-2}$ as a scale radius for galaxy sizes, masses, and mass-to-light ratios", MNRAS (submitted) https://arxiv.org/abs/2608.17680

The three-dimensional spatial light fraction is evaluated using the exact single-integral relation derived in Appendix A of the paper.

Accuracy and Limitations

• Exact Quantities: $b_n$, the ratio $R_5/R_{\rm e} = (2n/b_n)^n$, $F_{\rm 2D}$, and $F_{\rm 3D}$ are solved exactly from the Sérsic profile.
• Approximations: The analytic approximations for $g(n)$, $f(n)$, $h(n)$, and $Q(n)$ are validated for $0.25 \le n \le 10$. The virial coefficient fits $K_V(n, 0.1 R_{\rm e})$, $R_g/R_5$, and $K_V(n, \infty)$ are validated for $0.5 \le n \le 10$.

Citation

If you use R5Tools or the analytical conversions in your published research, please cite:

@ARTICLE{Graham2026_R5,
       author = {{Graham}, Alister W.},
        title = "{$R_{\rm e}$, or not $R_{\rm e}$: Developing $R_5 \equiv R_{-2}$ as a scale radius for galaxy sizes, masses, and mass-to-light ratios}",
      journal = {MNRAS, in press (arXiv:2608.17680)},
         year = 2026,
archivePrefix = {arXiv},
       eprint = {2608.17680},
 primaryClass = {astro-ph.GA},
          url = {https://arxiv.org/abs/2608.17680}
}

License

This project is licensed under the MIT License — see the LICENSE file for details.