Caustics Lightcurve

Hybrid light-curve evaluation adapted from the caustics package.

This module retains the contour-selection heuristics of Fran Bartolic’s caustics project while porting the implementation to JAX and the microJAX coordinate conventions. The main entry point, magnifications(), mixes the fast hexadecapole approximation with full finite-source contour integrations to deliver accurate light curves across binary and triple microlensing configurations.

Design highlights

  • JAX-native execution: relies on jax, jax.numpy, and jax.jit() to make the control flow differentiable and accelerator friendly.

  • Center-of-mass bookkeeping: transparently shifts source positions to the midpoint frame required by the polynomial image solver and restores them before returning magnifications.

  • Selective refinement: reuses the proximity and ghost-image tests from caustics to decide when the multipole estimate suffices.

External dependencies

  • jax (jax.numpy arrays and jit/lax primitives).

  • functools.partial for annotating static JIT parameters.

Internal collaborators

  • microjax.multipole — hexadecapole approximation.

  • microjax.caustics.extended_source — contour integration routines.

  • microjax.point_source — polynomial image finder used in the accuracy tests.

microjax.caustics.lightcurve.magnifications(w_points, rho, nlenses=2, npts_limb=200, limb_darkening=False, u1=0.0, npts_ld=100, **params)

Finite-source magnification samples along a caustic light curve.

The routine evaluates the magnification for each complex source position in w_points by reusing the caustics decision logic, adapted to microJAX’s center-of-mass conventions and JAX-native solvers. Depending on the local configuration it either applies microjax.multipole.mag_hexadecapole() or falls back to the full contour-integration path implemented in microjax.caustics.extended_source.mag_extended_source().

Parameters:

  • w_points (jax.Array) – Source-plane positions expressed in the center-of-mass frame of the first two lenses (or the lone lens when nlenses == 1).

  • rho (float) – Angular radius of the source in Einstein units.

  • nlenses (int, optional) – Number of point-mass lenses (1, 2, or 3). Defaults to 2.

  • npts_limb (int, optional) – Baseline number of uniformly spaced samples placed on the source limb before adaptive refinement during contour integrations. Defaults to 200.

  • limb_darkening (bool, optional) – When True, evaluate linear limb-darkening with coefficient u1. Defaults to False.

  • u1 (float, optional) – Linear limb-darkening coefficient used when limb_darkening is enabled. Defaults to 0.0.

  • npts_ld (int, optional) – Number of quadrature nodes for the Dominik (1998) P/Q integrals used in the limb-darkened branch. Defaults to 100.

  • **params (Any) –

    Lens parameters forwarded to the multipole and contour solvers. The expected keywords depend on nlenses:

    • nlenses == 1: none required.

    • nlenses == 2: s (separation) and q (mass ratio m2/m1).

    • nlenses == 3: s, q, q3 (m3/m1), r3 (modulus of the third lens position), and psi (azimuth of the third lens).

    Additional keyword arguments recognised by microjax.multipole.mag_hexadecapole(), microjax.caustics.extended_source.mag_extended_source(), or microjax.point_source._images_point_source() (for example custom root-solver settings) are propagated unchanged.

Returns:

Magnification evaluated at each entry of w_points.

Return type:

jax.Array

Notes

The routine temporarily shifts coordinates into the midpoint frame required by the polynomial root solver and shifts the images back before applying the multipole or contour integrations. For nlenses == 1 the multipole approximation is exact; for nlenses == 2 proximity and planetary tests decide whether it is used; for nlenses == 3 the algorithm always falls back to contour integration because the ghost-image test has not yet been generalised. Enabling limb darkening can increase runtime by up to an order of magnitude due to the extra quadrature.