diff --git a/README.md b/README.md index 8aa26d9..6bca8dc 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,29 @@ -# microlux +## microlux: Microlensing using Jax -This code is a Jax-based package that is used to calculate the binary lensing light curve with the finite source effect using the contour integration method. We inherit the novel features in VBBinaryLensing including parabolic correction and optimal sampling to maximize the performance. This is built on the JAX library which provides a NumPy-like interface with GPU and automatic differentiation support for high-performance machine learning research. Through automatic differentiation and our package, we get access to the accurate gradient for exploring more advanced algorithms. -## Installation +![Test Status](https://github.com/coastego/microlux/actions/workflows/run_test.yml/badge.svg) +[![Documentation Status](https://github.com/coastego/microlux/actions/workflows/build_docs.yml/badge.svg)](https://coastego.github.io/microlux/) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) +--- -You can install this package from the source by cloning the repository and running it after installing Jax. For the installation of Jax, please refer to the Jax installation guide. +`microlux` is a Jax-based package that can calculate the binary lensing light curve and its derivatives both efficiently and accurately. We use the modified adaptive contour integratoin in `VBBinaryLensing` to maximize the performance. +With the access to the gradient, we can use more advanced algorithms for microlensing modeling, such as Hamiltonian Monte Carlo (HMC) in `numpyro`. -``` bash -git clone https://github.com/CoastEgo/microlux.git +## Installation +The PyPI version is coming soon. Currently, You can install this package from the source code in the editable mode. +``` bash +git clone https://github.com/CoastEgo/microlux.git cd microlux - pip install -e . - ``` -## Usage - -The Jax version can calculate the gradient of the light curve using automatic differentiation. -There are examples in the ```test``` folder which show the light curve and gradient calculation. - -## Applications - -We can combine the Jax code with Numpyro for Hamiltonian Monte Carlo (HMC) sampling. There is a Jupyter notebook showing the application of HMC in modeling real microlensing events KMT-2019-BLG-0371 in the `example` folder. -## Features - -- [x] Optimal sampling and contour integration with error control to calculate the binary lens microlensing light curve with finite source effect. -- [x] Robust and accurate calculation: Widely test over the broad parameter space compared with VBBinaryLensing -- [x] Fast speed: Fully compatible with JIT compilation to speed up calculation. -- [x] Accurate gradient: Automatic differentiation with novel error estimator to ensure the convergence of gradient. -- [x] Aberth–Ehrlich method to find the roots of the polynomial and liner sum assignment algorithm to match the images -- [x] Application on real events modeling using NUTS in Numpyro - - - -## Future work +## Documentation +The documentation is available at here. See this for more details. -- [ ] High-order effects: parallax, orbital motion etc. -- [ ] Machine learning Applications. +## Citation -## Reference +`microlux` is open-source software licensed under the MIT license. If you use this package for your research, please cite our paper: -*under development* and Paper is coming soon. \ No newline at end of file +- A differentiable binary microlensing model using adaptive contour integration method: in arXiv \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f590f6f..28a0c9c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,18 +1,42 @@ # Welcome to microlux -microlux is a Jax-based package that is used to calculate the binary lensing light curve with the finite source effect using the contour integration method. We inherit the novel features in VBBinaryLensing including parabolic correction and optimal sampling to maximize the performance. This is built on the JAX library which provides a NumPy-like interface with GPU and automatic differentiation support for high-performance machine learning research. Through automatic differentiation and our package, we get access to the accurate gradient for exploring more advanced algorithms. +`microlux` is a Jax-based package that can calculate the binary lensing light curve and its derivatives both efficiently and accurately. We use the modified adaptive contour integratoin in `VBBinaryLensing` to maximize the performance. +With the access to the gradient, we can use more advanced algorithms for microlensing modeling, such as Hamiltonian Monte Carlo (HMC) in `numpyro`. ## Features -- Optimal sampling and contour integration with error control to calculate the binary lens microlensing light curve with finite source effect. -- Robust and accurate calculation: Widely test over the broad parameter space compared with VBBinaryLensing +- Adaptive contour integration with error control to calculate the binary lens microlensing light curve with finite source effect. +- Robust and accurate calculation: Widely test over the broad parameter space compared with `VBBinaryLensing`. - Fast speed: Fully compatible with JIT compilation to speed up calculation. -- Accurate gradient: Automatic differentiation with novel error estimator to ensure the convergence of gradient. -- Aberth–Ehrlich method to find the roots of the polynomial and liner sum assignment algorithm to match the images -- Application on real events modeling using NUTS in Numpyro +- Accurate gradient: Automatic differentiation with specially designed error estimator to ensure the convergence of gradient. +- Aberth–Ehrlich method to find the roots of the polynomial and Liner sum assignment algorithm to match the images. +- [Application](example/KB0371.ipynb) on the real event modeling. -## Reference -Under development and Paper is coming soon. ## Quick Start -Under development \ No newline at end of file +Please make sure that you have known the basic usage of `Jax`. Check the [Jax documentation](https://jax.readthedocs.io/en/latest/quickstart.html) for more details. +```python +import jax.numpy as jnp +from microlux import binary_mag + +b = 0.1 +t_0 = 0. +t_E = 1. +alphadeg = 270. +q = 0.2 +s = 0.9 +rho = 10 ** (-2) +trajectory_n = 1000 +times = jnp.linspace(t_0 - 1.0 * t_E, t_0 + 1.0 * t_E, trajectory_n) +#calculate the binary lensing magnification +mag = binary_mag(t_0, b, t_E, rho, q, s, alphadeg, times, tol=1e-3, retol=1e-3) +``` + +More examples can be found in the [`test`](https://github.com/CoastEgo/microlux/tree/master/test) folder. + +## Citation +If you use this package for your research, please cite our paper: + +- A differentiable binary microlensing model using adaptive contour integration method: in arXiv + +and consider starrring this repository on Github: \ No newline at end of file diff --git a/src/microlux/countour.py b/src/microlux/countour.py index f7aa56d..78046b6 100644 --- a/src/microlux/countour.py +++ b/src/microlux/countour.py @@ -85,6 +85,7 @@ def contour_integral( So we use this pre-define shaped array to solve this problem. **Parameters** + - For other parameters: please see at [`microlux.binary_mag`][] - `default_strategy`: The default strategy for the contour integration. The array length will be added gradually according to this strategy. For example, if the default_strategy is (60, 80, 150), the array length in each layer will be 60, 140, 290, respectively. @@ -93,7 +94,8 @@ def contour_integral( will slow down if only calculate the model without differentiation. Defaults to True. **Returns** - - result: A tuple containing the magnitude and the result of the contour integration. + + - `result`: A tuple containing the magnitude and the result of the contour integration. """ # JIT compile operation needs shape of the array to be determined.