Metadata-Version: 2.4
Name: rlds-cosmo
Version: 0.1.0
Summary: Cosmological application layer for Regime-Limited Dynamical Systems (RLDS)
Author-email: Aleksander Kubanski <aleksander@kubanski.pro>
License: MIT
Project-URL: Homepage, https://research.kubanski.pro
Project-URL: Documentation, https://github.com/AKubanski/rlds-cosmo#readme
Project-URL: Repository, https://github.com/AKubanski/rlds-cosmo
Project-URL: Issues, https://github.com/AKubanski/rlds-cosmo/issues
Project-URL: RLDS-MAT mathematical core, https://github.com/AKubanski/rlds-mat
Project-URL: RLDS-MAT DOI, https://doi.org/10.5281/zenodo.20342965
Project-URL: RLDS overview DOI, https://doi.org/10.5281/zenodo.19670133
Keywords: cosmology,dark energy,dark matter,MCMC,RLDS,attractor,phantom,GRB,DESI,Cobaya
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.5
Provides-Extra: mcmc
Requires-Dist: emcee>=3.0; extra == "mcmc"
Requires-Dist: corner>=2.2; extra == "mcmc"
Provides-Extra: cobaya
Requires-Dist: cobaya>=3.4; extra == "cobaya"
Provides-Extra: notebook
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: ipykernel; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Dynamic: license-file

# rlds-cosmo

**RLDS-COSMO** is the cosmological application layer of the Regime-Limited Dynamical Systems (RLDS) framework. It provides a reproducible high-redshift GRB forecast toolkit for testing the RLDS dark-sector closure against CPL/ΛCDM baselines.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![RLDS overview DOI](https://img.shields.io/badge/RLDS%20overview-10.5281%2Fzenodo.19670133-blue)](https://doi.org/10.5281/zenodo.19670133)

## Position in the RLDS software family

- **`rlds-mat`** is the mathematical core: RLDS reduction criteria, auxiliary-function geometry, attractor verification, and stability analysis.
- **`rlds-cosmo`** is the first application layer: shooting self-consistency for dark-sector cosmology, high-redshift GRB forecast machinery, and a Cobaya-compatible theory wrapper.

RLDS-MAT DOI: https://doi.org/10.5281/zenodo.20342965  
RLDS overview DOI: https://doi.org/10.5281/zenodo.19670133

## Headline GRB forecast

For the current RLDS posterior, the package reproduces the high-redshift GRB signature:

- median distance-modulus residual in `4 < z < 8`: about **−40 mmag** over the posterior;
- best-fit example: about **−32 mmag** in `4 < z < 8`;
- detection forecast at `σ_μ = 0.25 mag`: approximately **2.3σ for N_GRB = 200** and **>3σ for N_GRB = 500** for the posterior median signal;
- Cobaya-compatible theory wrapper for use in standard cosmological pipelines.

The sign convention is

```text
Δμ = μ_CPL+Planck − μ_RLDS
```

so a negative value means the RLDS prediction is brighter at high redshift than the CPL+Planck counter-fit.

## Installation

From a local checkout:

```bash
pip install -e .
```

After PyPI publication:

```bash
pip install rlds-cosmo
```

## Quick start

```python
from rlds_cosmo import ShootingRLDS, best_fit_params, predict_grb_residual

model = ShootingRLDS(**best_fit_params())

print(f"Omega_m = {model.Omega_m:.4f}")
print(f"w_eff(z=1) = {model.w_eff(1.0):.5f}")

result = predict_grb_residual(model)
print(f"<Δμ> z=4-8 = {result['avg_4_8_mmag']:+.1f} mmag")
print(f"CPL counter-fit: w0={result['w0_cpl']:+.3f}, wa={result['wa_cpl']:+.3f}")
```

Expected best-fit-scale output:

```text
Omega_m = 0.2998
w_eff(z=1) = -1.00149
<Δμ> z=4-8 = -32.1 mmag
```

## Command line

```bash
rlds-cosmo info
rlds-cosmo quickstart
rlds-cosmo headline --samples 100 --output grb_headline.png
```

The `headline` command regenerates the four-panel GRB figure from posterior samples.

## What is included

| Module | Purpose |
|---|---|
| `rlds_cosmo.model` | Core `ShootingRLDS` cosmology and observables |
| `rlds_cosmo.posterior` | Bundled posterior chain and propagation helpers |
| `rlds_cosmo.forecast` | GRB residual forecast and CPL counter-fit machinery |
| `rlds_cosmo.cobaya_module` | Cobaya `Theory` plugin |
| `rlds_cosmo.lcdm` | Reference ΛCDM utilities |

## Cobaya integration

```yaml
theory:
  rlds_cosmo.cobaya_module.RLDSTheory:
    speed: 50

params:
  K:       {prior: {min: 0.005, max: 0.25}, ref: 0.012}
  H0:      {prior: {min: 60.0,  max: 75.0}, ref: 67.44}
  R_c:     {prior: {min: 0.30,  max: 0.60}, ref: 0.51}
  Delta_R: {prior: {min: 0.03,  max: 0.20}, ref: 0.15}
  alpha:   {prior: {min: 3.01,  max: 3.30}, ref: 3.010}
  Omega_m_derived: {derived: true}
```

See `examples/02_cobaya_demo.py` and `examples/rlds_demo.yaml`.

## Reproducing the GRB figure

```bash
python examples/01_grb_headline.py
```

or, after installation:

```bash
rlds-cosmo headline --samples 200 --output grb_headline.png
```

Runtime depends on the number of posterior samples. A 100–200 sample run is enough for a fast reproducibility check; larger runs are used for publication figures.

## Important naming note

The distribution name is:

```text
rlds-cosmo
```

The Python import name is:

```python
import rlds_cosmo
```

The import package is intentionally **not** named `rlds`, to avoid conflicts with unrelated packages and to mirror the existing `rlds_mat` core package.

## Citing

If you use this code, cite the RLDS overview record:

> Kubanski, A. (2026). RLDS dark-sector research program. Zenodo. DOI: 10.5281/zenodo.19670133

When referring to the mathematical core, cite RLDS-MAT:

> RLDS-MAT DOI: 10.5281/zenodo.20342965

## License

MIT. See [LICENSE](LICENSE).
