Caustics

The lensing pipeline of the future: GPU-accelerated, automatically-differentiable, highly modular. Currently under heavy development: expect interface changes and some imprecise/untested calculations.

Installation

Simply install caustics from PyPI:

pip install caustics

Note: Python 3.11 is the minimum supported version for the latest caustics features.

Real World Example

Below is Figure 1 from Mind the information gap, by Legin et al. 2026, here we draw posterior samples from a detailed model of HST data (one of the SLACS lenses). The four dithered data images on the top row are combined into a single analysis for the model on the bottom row, the middle row shows the residuals. This shows the power of caustics to create state of the art lensing models!

Minimal Example

# fmt: off
import matplotlib.pyplot as plt
import caustics
import torch

cosmology = caustics.FlatLambdaCDM()
sie = caustics.SIE(cosmology=cosmology, name="lens", z_l=0.5, z_s=1.0, x0=-0.2, y0=0.0, q=0.4, phi=1.5708, Rein=1.7)
src = caustics.Sersic(name="source", x0=0.0, y0=0.0, q=0.5, phi=-0.985, n=1.3, Re=1.0, Ie=5.0)
lnslt = caustics.Sersic(name="lenslight", x0=-0.2, y0=0.0, q=0.8, phi=0.0, n=1.0, Re=1.0, Ie=10.0)

sim = caustics.LensSource(lens=sie, source=src, lens_light=lnslt, pixelscale=0.05, pixels_x=100)

plt.imshow(sim(), origin="lower")
plt.axis("off")
plt.show()

Batched simulator

sim.to_dynamic(False)
cosmology.to_static()
x = sim.get_values()
newx = x.repeat(20, 1)
newx += torch.normal(mean=0, std=0.1 * torch.ones_like(newx))

images = torch.vmap(sim)(newx)

fig, axarr = plt.subplots(4, 5, figsize=(20, 16))
for ax, im in zip(axarr.flatten(), images):
    ax.imshow(im, origin="lower")
plt.show()

Automatic Differentiation

J = torch.func.jacfwd(sim)(x)

# Plot the new images
fig, axarr = plt.subplots(3, 7, figsize=(20, 9))
for i, ax in enumerate(axarr.flatten()):
    ax.imshow(J[..., i], origin="lower")
plt.show()

Documentation

Please see our documentation page for more detailed information.

Contribution

We welcome contributions from collaborators and researchers interested in our work. If you have improvements, suggestions, or new findings to share, please submit an issue or pull request. Your contributions help advance our research and analysis efforts.

To get started with your development (or fork), click the "Open with GitHub Codespaces" button below to launch a fully configured development environment with all the necessary tools and extensions.

Instruction on how to contribute to this project can be found in the CONTRIBUTION.md

Some guidelines:

• Please use isort and black to format your code.
• Use CamelCase for class names and snake_case for variable and method names.
• Open up issues for bugs/missing features.
• Use pull requests for additions to the code.
• Write tests that can be run by pytest.

Thanks to our contributors so far!