VBMicrolensing

VBMicrolensing is a tool for efficient computation in gravitational microlensing events using the advanced contour integration method, supporting single, binary and multiple lenses.

In particular, VBMicrolensing is designed for the following calculations:

• Magnification by single, binary and multiple lenses
• Centroid of the images generated by single and binary lenses
• Critical curves and caustics of binary and multiple lenses
• Complete light curves including several higher order effects: limb darkening of the source, binary source, parallax, xallarap, circular and elliptic orbital motion.

VBMicrolensing is written as a C++ library and wrapped as a Python package, the user can call the code from either C++ or Python. This new code encompasses the well-known VBBinaryLensing code, which is at the basis of several platforms for microlensing modeling. VBBinaryLensing will still be available as a legacy software, but will no longer be maintained.

VBMicrolensing has been developed by Valerio Bozza, University of Salerno, with a substantial contribution by Vito Saggese, University of Naples and Jiyuan Zhang, Tisnghua University. We also acknowledge a long list of collaborators who contributed to testing and development of particular aspects over the years: Natasha Abrams, Etienne Bachelet, Fran Bartolic, Dex Bhadra, Sebastiano Calchi Novati, Giovanni Covone, Giuseppe D'Ago, Jason Eastman, Alvaro Gutierrez, Tyler Heintz, Ava Hoag, Markus Hundertmark, Elahe Khalouei, Jessica Lu, Amber Malpas, Lawrence Peirson, Matthew Penny, Radek Poleski, Haibin Ren, Paolo Rota, Sedighe Sajadian, Rachel Street, Keto Zhang, Weicheng Zhang, Wei Zhu.

Attribution

Any use of this code for scientific publications should be acknowledged by a citation to the works relevant to your study:

• V. Bozza, MNRAS 408 (2010) 2188: general algorithm for binary lensing;
• V. Bozza, E. Bachelet, F. Bartolic, T. Heintz, A. Hoag, M. Hundertmark, MNRAS 479 (2018) 5157: BinaryMag2 function, Extended-Source-Point-Lens methods;
• V. Bozza, E. Khalouei and E. Bachelet, MNRAS 505 (2021) 126: astrometry, generalized limb darkening, Keplerian orbital motion;
• V. Bozza, v. Saggese, G. Covone, P. Rota & J. Zhang, A&A 694 (2025) 219: multiple lenses.

If specifically relevant to your work, please also cite J. Skowron and A. Gould, arXiv:1203.1034.

Installation

Python

The easiest way to install VBMicrolensing is through pip install VBMicrolensing.

Pre-built packages are available on conda-forge under the name vbmicrolensing:

conda install -c conda-forge vbmicrolensing

If you use mamba or micromamba:

mamba install -c conda-forge vbmicrolensing

In alternative, in order to use the latest build, clone this GitHub repository on your computer, enter your local copy of the repository and run

pip install .

Currently, VBMicrolensing works on Linux, Windows, MacOS and python >= 3.8. The package requires a C++ compiler supporting C++17.

C++

If you just want to use the C++ library, clone this repository, all cpp files and the VBMicrolensing.h are located in in VBMicrolensing/lib and should be added to your project.

The package also contains the following files:

• VBMicrolensing/data/ESPL.tbl - Pre-calculated table for Extended-source-point-lens
• VBMicrolensing/data/SunEphemeris.txt - Sun ephemeris for parallax calculation
• VBMicrolensing/data/OB151212coords.txt - Sample file with event coordinates
• VBMicrolensing/data/satellite1.txt - Sample table for satellite position (Spitzer)
• VBMicrolensing/data/satellite2.txt - Sample table for satellite position (Kepler)

Documentation

Full documentation for the use of VBmicrolensing in python and documentation for the use of VBmicrolensing in C++ are available.

Furthermore, the vast majority of functions are documented with Python docstrings which can be accessed as, for example, ?VBBL.BinaryMag2() in a Jupyter notebook.

We also provide some examples showing the capabilities of the package. In particular, we reproduce some known triple-lense microlensing events.

License

VBMicrolensing is freely available to the community under the GNU Lesser General Public License Version 3 included in this repository.