MAGSIM — Finite-Source Binary-Lens Microlensing Simulator

MAGSIM simulates gravitational microlensing light curves produced by a binary lens (e.g., a star with an orbiting planet) acting on a finite, limb-darkened background source star. Magnification is computed via inverse ray-shooting: rays are cast across a grid in the lens plane, deflected according to the binary lens equation, and their arrival density in the source plane is integrated over the source's angular disk to give the total magnification at each epoch.

The included worked example models MOA-2009-BLG-319Lb, a sub-Saturn-mass planet discovered via high-magnification microlensing (Miyake et al. 2011, ApJ 728, 120; arXiv:1010.1809; reanalyzed in Bhattacharya et al. 2021, arXiv:2009.08461), and validates the simulated curve against photometry from five independent observatories.

What's in this repository

File	Purpose
MAGSIM.ipynb	Main notebook: lens/source model, ray-shooting simulation, geometry plots, interactive explorer, and validation against real data.
MAGSIMdt.txt	Precomputed magnification light curve (HJD vs. magnification) for the worked example, so you can explore the notebook without re-running the full simulation.
UID_0300138_PLC_*.tbl	Real photometric data for the worked example, one file per observatory. These must stay in the same directory as the notebook (the notebook reads them via relative filename). See DATA_PROVENANCE.md for column format and required follow-up before publishing.
requirements.txt	Python dependencies.
LICENSE	Project license.
CITATION.cff	Citation metadata (edit before publishing — see below).

Requirements

• Python ≥ 3.9
• See requirements.txt for packages (numpy, pandas, matplotlib, ipywidgets)

pip install -r requirements.txt

If running in Jupyter Notebook (not JupyterLab), enable the widgets extension for the interactive explorer cell:

jupyter nbextension enable --py widgetsnbextension

Quick start

git clone https://github.com/deepaksuthar8018/MagSim
cd magsim
pip install -r requirements.txt
jupyter notebook MAGSIM.ipynb

Run all cells top to bottom. The ray-shooting simulation (the cell that regenerates MAGSIMdt.txt) is the most computationally expensive step — at the default grid resolution (N = 10000) it can take several minutes and several GB of memory. If MAGSIMdt.txt is already present and you haven't changed the lens/source parameters, you can skip re-running that cell and go straight to the plotting and validation cells.

Method summary

Given a binary lens of mass ratio q and separation s (in units of the Einstein radius θ_E), and a source of angular radius ρ with linear limb darkening coefficient Γ:

1. Deflection field. Each lens component deflects a ray at angular position θ by α(θ) = Σᵢ mᵢ(θ − θLᵢ)/|θ − θLᵢ|² (point-mass deflection, Einstein-radius units).
2. Critical curves / caustics. The Jacobian of the lens mapping is computed analytically (not by finite differencing) to locate critical curves in the lens plane and their corresponding caustics in the source plane.
3. Finite-source magnification. For each time step, a grid of rays is shot through the lens plane, mapped to the source plane, and the fraction landing within the source's limb-darkened disk (of radius ρ, centered on the source's instantaneous position) is integrated and normalized by the source's total (unlensed) flux to give the magnification.
4. Validation. The resulting magnification curve is compared against real photometric time series from multiple observatories, with per-instrument flux calibration (flux = f_s · A(t) + f_b) fit by weighted least squares.

Validating against your own event

To model a different microlensing event:

1. Replace the lens/source parameters in the parameter-definition cell with the published values for your target event (separation, mass ratio, impact parameter, trajectory angle, source radius, limb-darkening coefficient, t₀, t_E).
2. Update the simulation time window to bracket the event.
3. Re-run the ray-shooting cell.
4. If comparing to real photometry, fit f_s/f_b per dataset by weighted least squares against your simulated curve rather than hand-tuning — see the validation cell for the pattern.

Citation

If you use this code, please cite it — see CITATION.cff.

License

See LICENSE. This repository defaults to the MIT License.

Acknowledgments

Developed as part of thesis research on cosmological simulation and gravitational lensing, as an extension to my master's thesis. Validation data are drawn from the public microlensing photometry archive associated with Miyake et al. (2011) — see DATA_PROVENANCE.md for full provenance.