Metadata-Version: 2.4
Name: welcome-to-the-universe
Version: 0.1.4
Summary: Theory-driven full-sky weak-lensing convergence-map realisations
Author-email: Jisu Samuel Kim <jisu.samuel.kim@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/JisuSamuelKim/WELCOME
Project-URL: Repository, https://github.com/JisuSamuelKim/WELCOME
Keywords: cosmology,weak lensing,full sky,HEALPix,emulator
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: matplotlib>=3.7
Requires-Dist: healpy>=1.16
Requires-Dist: camb>=1.5
Requires-Dist: astropy>=5.3
Requires-Dist: joblib>=1.3
Dynamic: license-file

# WELCOME to the Universe

**WELCOME** (WEak-Lensing COnvergence Map Emulator) is a theory-driven framework for generating stochastic full-sky weak-lensing convergence-map realisations from cosmological parameters and a source population.

## Installation

After the package is released on PyPI:

```bash
pip install welcome-to-the-universe
```

Before a PyPI release, the GitHub repository can be installed directly:

```bash
pip install git+https://github.com/JisuSamuelKim/WELCOME.git
```

For development from a local clone:

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

## Minimal use

```python
from welcome import WelcomeConfig, run_welcome

config = WelcomeConfig(
    h=0.70,
    omega_b=0.046,
    omega_cdm=0.233,
    sigma8=0.82,
    n_s=0.97,
    single_plane=True,
    source_redshift=1.0334,
    nside=512,
    n_realisations=10,
)

result = run_welcome(config)
```

For a source redshift distribution, set `single_plane=False` and provide `nz_file` as a NumPy `.npy` array with shape `(N, 2)` or `(2, N)`, containing `z` and `n(z)`.

## Example notebook

`examples/run_WELCOME.ipynb` demonstrates the complete workflow and then displays:

- one generated full-sky convergence realisation,
- the configured source population,
- matched theoretical and emulated power-spectrum realisations,
- theoretical and emulated wavelet L1-norm curves at 15-30, 18-36, 20-40, and 25-50 arcmin,
- L1-weighted variance, skewness, and excess kurtosis.

The theoretical wavelet L1 prediction at a fixed cosmology and source population is deterministic. The emulation moment panel therefore shows one theory value per scale and an empirical distribution across generated map realisations.

## Outputs

Theoretical power-spectrum products are stored as compressed `.npz` files. Generated convergence maps retain the existing `.npy` map format. Diagnostic products generated by the example notebook are also cached as `.npz` files inside the run output directory.

## Licence

MIT License. See `LICENSE`.
