Metadata-Version: 2.1
Name: VBMicrolensing
Version: 5.5
Summary: VBMicrolensing is a tool for efficient computation in gravitational microlensing events using the advanced contour integration method, supporting single, binary and multiple lenses.
Keywords: Microlensing magnification and astrometry
Author-Email: Valerio Bozza <valboz@sa.infn.it>, Vito Saggese <vitosaggese.vs@gmail.com>
License: LGPL-3.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Project-URL: Homepage, https://github.com/valboz/VBMicrolensing
Requires-Python: <4,>=3.8
Requires-Dist: numpy
Description-Content-Type: text/markdown

# 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](https://github.com/valboz/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, 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](https://ui.adsabs.harvard.edu/abs/2010MNRAS.408.2188B/abstract): general algorithm for binary lensing;
- [V. Bozza, E. Bachelet, F. Bartolic, T. Heintz, A. Hoag, M. Hundertmark, MNRAS 479 (2018) 5157](https://ui.adsabs.harvard.edu/abs/2018MNRAS.479.5157B/abstract): BinaryMag2 function, Extended-Source-Point-Lens methods; 
- [V. Bozza, E. Khalouei and E. Bachelet, MNRAS 505 (2021) 126](https://ui.adsabs.harvard.edu/abs/2021MNRAS.505..126B/abstract): astrometry, generalized limb darkening, Keplerian orbital motion; 
- [V. Bozza, v. Saggese, G. Covone, P. Rota & J. Zhang, A&A 694 (2025) 219](https://ui.adsabs.harvard.edu/abs/2025A%26A...694A.219B/abstract): multiple lenses.

If specifically relevant to your work, please also cite
[J. Skowron and A. Gould, arXiv:1203.1034](https://arxiv.org/abs/1203.1034).
 
## Installation

### Python

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

Pre-built packages are available on [conda-forge](https://anaconda.org/conda-forge/vbmicrolensing) under the name `vbmicrolensing`:

```bash
conda install -c conda-forge vbmicrolensing
```

If you use [mamba](https://mamba.readthedocs.io/) or [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html):

```bash
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](/docs/python/readme.md) and [documentation for the use of VBmicrolensing in C++](/docs/C++/readme.md) 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](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.
