Inverse-Ray Lightcurve

Adaptive light-curve computation combining multipole and inverse-ray solvers.

This module couples the hexadecapole approximation with selective inverse-ray finite-source integrations to deliver accurate binary- and triple-lens light curves while keeping GPU/CPU cost manageable. The key routines exported here are mag_binary() and mag_triple().

Design highlights

Hexadecapole-first evaluation: start from the multipole estimate and upgrade only samples that fail the accuracy heuristics.
Hybrid triggers: combine caustic-proximity and planetary-caustic tests to decide when a full inverse-ray solve is required.
Chunked batching: evaluate inverse-ray calls in configurable chunks to balance memory usage and accelerator occupancy.
Limb-darkening aware: support both uniform and linear limb-darkened profiles through the u1 parameter.
Shared infrastructure: binary and triple lenses reuse the same chunking and integration utilities, so configuration parameters have consistent effects.

Workflow outline

Build a complex source-plane trajectory w_points.
Call mag_binary() or mag_triple() with lens parameters and integration settings.
Feed the returned magnifications into downstream likelihoods (see microjax.likelihood).

References

Miyazaki & Kawahara (in prep.) — description of the adaptive microJAX solver stack (forthcoming).

microjax.inverse_ray.lightcurve.mag_binary(w_points: Array, rho: float, r_resolution: int = 1000, th_resolution: int = 1000, u1: float = 0.0, delta_c: float = 0.01, Nlimb: int = 500, bins_r: int = 50, bins_th: int = 120, margin_r: float = 1.0, margin_th: float = 1.0, MAX_FULL_CALLS: int = 500, chunk_size: int = 100, **params) → Array

Binary-lens finite-source magnification with adaptive inverse-ray refinement.

The input trajectory w_points is interpreted as one-dimensional complex positions in the source plane (Einstein-radius units). The function recentres these coordinates on the binary centre of mass defined by the supplied separation s and mass ratio q, evaluates point-source images via microjax.point_source._images_point_source(), and obtains the hexadecapole approximation with microjax.multipole.mag_hexadecapole(). The accuracy tests in microjax.inverse_ray.cond_extended provide a boolean mask test that marks positions where the multipole solution is sufficient. Up to MAX_FULL_CALLS entries failing the tests are reordered to the front of the array and recomputed with microjax.inverse_ray.extended_source.mag_uniform() when u1 = 0 or microjax.inverse_ray.extended_source.mag_limb_dark() otherwise. Entries beyond this budget retain the hexadecapole magnification.

Parameters

w_points (Array) – One-dimensional complex jax.Array of source-plane coordinates (x + 1j*y) sampled along the trajectory. The returned magnification array preserves the same ordering.
rho (float) – Angular source radius in Einstein units.
r_resolution (int, optional) – Number of uniformly spaced radial samples per polar cell used by the inverse-ray integrator.
th_resolution (int, optional) – Number of uniformly spaced angular samples per polar cell used by the inverse-ray integrator.
u1 (float, optional) – Linear limb-darkening coefficient. Use 0 for a uniform surface brightness.
delta_c (float, optional) – Dimensionless smoothing threshold supplied to microjax.inverse_ray.boundary.calc_facB() in the limb-darkened integrator.
Nlimb (int, optional) – Number of source-limb samples traced through the lens to seed the polar region construction.
bins_r (int, optional) – Number of histogram bins used when clustering limb radii into polar subregions; larger values resolve smaller radial features.
bins_th (int, optional) – Number of histogram bins used when clustering limb angles into polar subregions.
margin_r (float, optional) – Radial margin applied to each subregion in units of rho.
margin_th (float, optional) – Angular margin applied to each subregion, expressed in degrees (converted to radians internally).
MAX_FULL_CALLS (int, optional) – Maximum number of points replaced by the inverse-ray finite-source solver. Setting MAX_FULL_CALLS = 0 disables the refinement stage.
chunk_size (int, optional) – Number of refined points evaluated per jax.vmap() batch when the inverse-ray solver is invoked.
**params – Lens-configuration keywords forwarded to the point-source and inverse-ray solvers. s (projected separation) and q (companion-to-host mass ratio) are mandatory; any additional entries understood by the low-level routines are forwarded unchanged.

Returns

Real-valued magnification array with the same shape as w_points.

Return type

Array

Notes

test is True where the multipole solution is accepted; indices with False are ordered first and considered for refinement in that order.
MAX_FULL_CALLS = 0 produces a purely hexadecapole light curve.
Source positions are shifted internally to the lens centre-of-mass frame, while the public interface accepts unshifted coordinates.
Results are evaluated lazily by JAX; call mags.block_until_ready() to enforce synchronisation when required.

microjax.inverse_ray.lightcurve.mag_triple(w_points: Array, rho: float, r_resolution: int = 1000, th_resolution: int = 1000, u1: float = 0.0, delta_c: float = 0.01, Nlimb: int = 500, bins_r: int = 50, bins_th: int = 120, margin_r: float = 1.0, margin_th: float = 1.0, MAX_FULL_CALLS: int = 500, chunk_size: int = 50, **params) → Array

Triple-lens magnification with a multipole baseline and limited refinement.

The procedure is analogous to mag_binary(). The trajectory is shifted to the centre of mass implied by s and q, point-source images are evaluated with nlenses = 3, and the hexadecapole approximation provides the baseline magnification. Because specialised accuracy tests for triple lenses are not yet available, the boolean mask test is False at all entries. Consequently jnp.argsort(test) produces the original ordering and the first MAX_FULL_CALLS elements are recomputed with microjax.inverse_ray.extended_source.mag_uniform() for u1 = 0 or microjax.inverse_ray.extended_source.mag_limb_dark`() otherwise. The remaining points retain their hexadecapole magnifications.