herculens

Differentiable strong lens modelling on CPUs and GPUs

https://github.com/herculens/herculens

Science Score: 67.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 1 DOI reference(s) in README
✓
Academic publication links
Links to: arxiv.org, joss.theoj.org
○
Academic email domains
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.9%) to scientific vocabulary

Last synced: 6 months ago · JSON representation ·

Repository

Differentiable strong lens modelling on CPUs and GPUs

Basic Info

Host: GitHub
Owner: Herculens
License: mit
Language: Jupyter Notebook
Default Branch: main
Homepage:
Size: 126 MB

Statistics

Stars: 27
Watchers: 5
Forks: 8
Open Issues: 4
Releases: 5

Created over 4 years ago · Last pushed 7 months ago

Metadata Files

Readme Changelog License Citation Authors

Herculens: differentiable gravitational lensing

License

Analysis of strong lensing imaging data

The primary purpose of Herculens is to provide flexible modeling methods to model current and future observations of strong gravitational lenses. Currently, it supports various degrees of model complexity, ranging from standard smooth analytical profiles to pixelated models combined with machine learning approaches.

Currently, Herculens supports several of the most widely-used analytical profiles, as well as multi-scale pixelated models regularized with wavelets. Future updates will include the support of point source modeling, new regularization techniques, and more expressive models based on neural networks.

`JAX`-based automatic differentiation and code compilation

Herculens is based on the powerful framework of differentiable programming. The code is entirely based on the automatic differentiation and compilation features of JAX. This simply means that you have access, analytically, to all partial derivatives of your model with respect to any of its parameters. This enables faster convergence to the solution, more efficient exploration of the parameter space including the sampling of posterior distributions, and new ways to mitigate degeneracies that affect gravitational lensing.

This highly modular framework offers a way to merge all modeling paradigms explored in the literature, into a single tool:

analytical: model components are described by analytical functions with few parameters and clear physical meaning, but that may be insufficient to fit all observations;
pixelated: regular or irregular grid of pixels are used as individual parameters, which offer higher flexibility, but requires well-motivated regularization strategies;
deep learning: neural networks (among others) are by construction fully differentiable, regardless of being pre-trained or not. It is therefore effortless to plug-in any deep learning-based model component to Herculens.

Being based on JAX means that Herculens runs effortlessly on CPUs, GPUs and TPUs with no changes to the code.

Works using `Herculens`

You can find a list of analyses that used Herculens, as well as their ADS bibtex entries, on this page.

Example notebooks

Several examples to run Herculens in many different situations are available in the herculens_workspace repository.

Installation

Manual installation

The package will be soon available through PyPi directly, but it is as easy to install it manually. It has been texted against Python 3.7, but should work with Python 3.8 or more recent versions.

Good practice is to create a new python environment: sh conda create -n herculens-env python=3.12 conda activate herculens-env

Download the package cd into the directory. Then install the local Herculens package (or use -e for a development install) as follows: sh pip install (-e) .

The mandatory dependencies will be installed automatically.

Package requirements

The requirements.txt file lists all required and optional package dependencies, along with their specific versions. IMPORTANT NOTE: do not only install blindly the required packages; please also have a look at the content of the file itself to learn more about additional optional packages, depending on your goals.

Attribution

Citation

If you make use of Herculens, please cite Galan et al. 2022. If you use the CorrelatedField model, please also cite Galan et al. 2024. You will find in this file the related bibtex entries.

Special mention regarding Lenstronomy

Part of the Herculens code originates from the open-source lens modeling software package lenstronomy, described in Birrer et al. 2021 (and references therein). In every source file, proper credits are given to the specific developers and contributors to both the original lenstronomy (up to version 1.9.3) and Herculens.

Contributors

The list of people that contributed to Herculens and credits to original lenstronomy contributors, is in this document.

Owner

Name: Herculens
Login: Herculens
Kind: organization

Repositories: 1
Profile: https://github.com/Herculens

Ensemble of repositories related to lens modeling analyses using Herculens

Citation (CITATION.md)

# Citing Herculens

If you make use of `Herculens`, please cite [Galan et al. 2022](https://ui.adsabs.harvard.edu/abs/2022A%26A...668A.155G/abstract). This work presents the global architecture of the tool, and applies it to reconstruct a pixelated lens potential with wavelets.

```
@ARTICLE{Galan2022,
       author = {{Galan}, A. and {Vernardos}, G. and {Peel}, A. and {Courbin}, F. and {Starck}, J. -L.},
        title = "{Using wavelets to capture deviations from smoothness in galaxy-scale strong lenses}",
      journal = {\aap},
     keywords = {galaxies: structure, dark matter, methods: data analysis, gravitation, gravitational lensing: strong, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics, Astrophysics - Astrophysics of Galaxies},
         year = 2022,
        month = dec,
       volume = {668},
          eid = {A155},
        pages = {A155},
          doi = {10.1051/0004-6361/202244464},
archivePrefix = {arXiv},
       eprint = {2207.05763},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2022A&A...668A.155G},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```

In addition, if you combine `Herculens` with `nifty`, for example using the `CorrelatedField` model, please also cite [Galan et al. 2024](https://ui.adsabs.harvard.edu/abs/2024arXiv240218636G/exportcitation). Along with the above publication, please also cite the `NIFTy.re` paper from [Edenhofer et al. 2024](https://ui.adsabs.harvard.edu/abs/2024JOSS....9.6593E/abstract).

```
@ARTICLE{Galan2024,
       author = {{Galan}, A. and {Caminha}, G.~B. and {Knollm{\"u}ller}, J. and {Roth}, J. and {Suyu}, S.~H.},
        title = "{El Gordo needs El Anzuelo: Probing the structure of cluster members with multi-band extended arcs in JWST data}",
      journal = {arXiv e-prints},
     keywords = {Astrophysics - Astrophysics of Galaxies, Astrophysics - Cosmology and Nongalactic Astrophysics, Astrophysics - Instrumentation and Methods for Astrophysics},
         year = 2024,
        month = feb,
          eid = {arXiv:2402.18636},
        pages = {arXiv:2402.18636},
          doi = {10.48550/arXiv.2402.18636},
archivePrefix = {arXiv},
       eprint = {2402.18636},
 primaryClass = {astro-ph.GA},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2024arXiv240218636G},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```

GitHub Events

Total

Create event: 6
Release event: 3
Issues event: 4
Watch event: 4
Delete event: 5
Issue comment event: 15
Push event: 99
Pull request review event: 1
Pull request event: 23

Last Year

Create event: 6
Release event: 3
Issues event: 4
Watch event: 4
Delete event: 5
Issue comment event: 15
Push event: 99
Pull request review event: 1
Pull request event: 23

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 3
Total pull requests: 8
Average time to close issues: 29 minutes
Average time to close pull requests: 13 days
Total issue authors: 1
Total pull request authors: 2
Average comments per issue: 0.33
Average comments per pull request: 0.5
Merged pull requests: 6
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 3
Pull requests: 8
Average time to close issues: 29 minutes
Average time to close pull requests: 13 days
Issue authors: 1
Pull request authors: 2
Average comments per issue: 0.33
Average comments per pull request: 0.5
Merged pull requests: 6
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

aymgal (5)
WolfgangEnzi (1)

Pull Request Authors

aymgal (13)
CKrawczyk (1)
ahuang314 (1)
martin-millon (1)

Top Labels

Issue Labels

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- pypi 104 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 3
Total maintainers: 1

pypi.org: herculens

Auto-differentiable strong lens modelling

Homepage: https://github.com/Herculens/herculens
Documentation: https://herculens.readthedocs.io/
License: MIT
Latest release: 0.2.3
published 8 months ago

Versions: 3
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 104 Last month

Rankings

Dependent packages count: 9.6%

Average: 32.0%

Dependent repos count: 54.3%

Maintainers (1)

aymgal