NOTICE

This is a legacy package no longer maintained. Please use the new package VBMicrolensing, which contains all the functions of VBBinaryLensing with further optimizations and support for multiple lensing!

VBBinaryLensing

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

In particular, VBBinaryLensing is designed for the following calculations:

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

The code has been developed by Valerio Bozza, University of Salerno. It is written as a C++ library and wrapped as a Python package, the user can call the code from either C++ or Python.

The root finding algorithm has been adopted from Jan Skowron & Andy Gould (http://www.astrouw.edu.pl/~jskowron/cmplx_roots_sg/) and translated to C++ by Tyler M. Heintz and Ava R. Hoag. The new Python wrapper has been created by Fran Bartolić in collaboration with Etienne Bachelet and Markus Hundertmark.

VBBinaryLensing is also adopted by several user-friendly modeling platforms for microlensing:

These platforms offer high-level frameworks for easy modeling of microlensing events. Consider using those codes if you do not want to develop your own modeling or simulation code. On the other hand, if you need direct access to basic functions to include in your own project, this is the right place for you.

A selection of recent reviews about microlensing and its applications can be found here.

Attribution

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

V. Bozza, MNRAS 408 (2010) 2188: general algorithm for binary lensing;
V. Bozza et al., 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.

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

Installation

Python

The easiest way to install VBBinaryLensing is through pip

pip install VBBinaryLensing

If you want the latest development version from Github, clone this repository and run

python setup.py install

Currently, VBBinaryLensing works on Linux, Windows, MacOS and python >= 2.7. The python package requires pybind11 which can be installed with

pip install pybind11

The package requires a C++ compiler supporting C++.

C++

If you just want to use the C++ library, clone this repository, the library files VBBinaryLensingLibrary.cpp and VBBinaryLensing.h are located in in VBBinaryLensing/lib. An example usage of the C++ code is provided in examples/cpp_examples together with a sample Makefile for compiling the library.

The package also contains the following files:

examples/cpp_examples/instructions.cpp - Contains working examples and specific instructions for all functions.
VBBinaryLensing/data/ESPL.tbl - Pre-calculated table for Extended-source-point-lens
VBBinaryLensing/data/OB151212coords.txt - Sample file with event coordinates
VBBinaryLensing/data/satellite1.txt - Sample table for satellite position (Spitzer)
VBBinaryLensing/data/satellite2.txt - Sample table for satellite position (Kepler)

Example usage

To check the installation, try:

>>>import VBBinaryLensing

# Initialize the VBBinaryLensing object which contains all functions 
>>>VBBL = VBBinaryLensing.VBBinaryLensing()

>>>s = 1.
>>>q = 0.02
>>>y1 = 0.5 
>>>y2 = 0.5 
>>>rho = 0.0033

# Calculate magnification for a single point in the source plane
>>>magnification = VBBL.BinaryMag2(s, q, y1, y2, rho)
>>>print(magnification)
>>>1.6310924403681109

Example Jupyter notebooks are included in examples/python_examples.

Documentation

Full documentation for the use of VBBinaryLensing in C++ is available. This can be a good reference also for Python users.

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

Note that the python wrapper does not support the user-defined limb-darkening law.

License

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

valboz/VBBinaryLensing