update docs and readme

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 <a href='https://github.com/valboz/VBBinaryLensing'>VBBinaryLensing</a> including parabolic correction and optimal sampling to maximize the performance. This is built on the <a href='https://github.com/google/jax'>JAX</a> 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 <a href='https://github.com/google/jax#installation'>Jax installation guide. </a>
+`microlux` is a <a href='https://github.com/jax-ml/jax'>Jax</a>-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 <a href='https://github.com/valboz/VBBinaryLensing'>`VBBinaryLensing`</a> 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 <a href='https://num.pyro.ai/en/latest/mcmc.html#numpyro.infer.hmc.NUTS'>`numpyro`</a>.
 
-``` 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 <a href='https://jax.readthedocs.io/en/latest/notebooks/autodiff_cookbook.html'>automatic differentiation</a>.
-There are examples in the ```test``` folder which show the light curve and gradient calculation.
-
-## Applications
-
-We can combine the Jax code with <a href='https://github.com/pyro-ppl/numpyro'>Numpyro</a> 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 <a href='https://coastego.github.io/microlux/'>here</a>. 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.
+- A differentiable binary microlensing model using adaptive contour integration method: <a href='https://arxiv.org/abs/2501.07268'>in arXiv</a>

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 <a href='https://github.com/valboz/VBBinaryLensing'>VBBinaryLensing</a> including parabolic correction and optimal sampling to maximize the performance. This is built on the <a href='https://github.com/google/jax'>JAX</a> 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 <a href='https://github.com/jax-ml/jax'>Jax</a>-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 <a href='https://github.com/valboz/VBBinaryLensing'>`VBBinaryLensing`</a> 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 <a href='https://num.pyro.ai/en/latest/mcmc.html#numpyro.infer.hmc.NUTS'>`numpyro`</a>.
 
 ## 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.
+- <a href='https://en.wikipedia.org/wiki/Aberth_method'>Aberth–Ehrlich</a> method to find the roots of the polynomial and <a href='https://docs.scipy.org/doc/scipy-1.15.0/reference/generated/scipy.optimize.linear_sum_assignment.html'>Liner sum assignment </a> 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
+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: <a href='https://arxiv.org/abs/2501.07268'>in arXiv</a>
+
+and consider starrring this repository on <a href='https://github.com/CoastEgo/microlux'>Github</a>:

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.