This repository contains source code for
- generating microlensing magnification maps,
- locating microlensing critical curves and caustics, and
- determining the number of microlensing caustic crossings,
all on GPUs.
We utilize Inverse Polygon Mapping (IPM, Mediavilla et al. 2006, 2011), combined with the Fast Multipole Method (FMM, Greengard and Rokhlin 1987) as suggested and used by Jiménez-Vicente and Mediavilla (2022) for CPUs, in order to generate magnification maps. Calculations for allocating the areas of the IPM cells among the pixels to which they map use the Sutherland-Hodgman (1974) algorithm.
We use Witt's (1990) method to locate the microlensing critical curves and caustics, while taking advantage of the FMM again to decrease computation time for terms involving derivatives of the microlensing potential. In order to locate the roots of the parametric critical curve equation, we employ the Aberth-Ehrlich method, a cubically convergent algorithm that allows for simultaneous approximations of the roots of a polynomial.
We use the fact that the caustics are clockwise (under the chosen critical curve parametrization) oriented closed curves to utilize the winding number in order to calculate a two dimensional map of the the number of caustic crossings (Wambsganss et al. 1992, Granot et al. 2003). We use Sunday's (2001) algorithm to calculate the winding number of the discretized caustic polygons around the center of every pixel, efficiently creating a map that provides the number of caustic crossings.
You are free to use this code under the provided license. If you happen to use it for any work that leads to publications, it would be much appreciated if you cite the appropriate paper for either creating magnification maps (here), or for calculating critical curves, caustics, and the number of caustic crossings (here).
I make no promise that the current state of the code will stay the same, or that things will always be backwards compatible. Poor design choices I made in the past may need be changed to make the future better! Suggested improvements and bugfixes are also always appreciated.
I would love to be considered for involvement in any projects which make use of these tools, as I'd like to think I bring a bit of microlensing knowledge to the table :). I can be reached at [email protected].
The code is written to be independent of anything besides the C++ standard libraries and the Thrust libraries that come with CUDA. We implement IPM, the FMM, the Sutherland-Hodgman algorithm, the Aberth-Ehrlich method, and Sunday's algorithm ourselves.
The bulk of the code is written using NVIDIA's CUDA, and you will need a CUDA installation to compile and run it. We additionally require a C++20 compliant compiler.
The include directory contains the bulk of the code, which is written mostly as templated objects and functions. The src directory contains files for creating executables and libraries. The bin directory holds compilation output. The microlensing directory contains python code for ease of use, while the examples directory contains example python notebooks outlining usage.
Compilation has been tested with the GNU compiler version 11.2.0 and the CUDA compiler version 12.4.
First, clone the repository.
git clone https://github.com/weisluke/microlensing.git
Then, simply run
source compile
to run the compilation file. This should create 5 executables and 4 libraries in the bin directory.
I'll note that this repository contains the 4 libraries precompiled and placed in the ./microlensing/lib/ directory already. These libraries may or may not work on your hardware, as they were compiled for a particular cluster (NERSC), but you can try running the example python notebooks first to see if they do. They should work for Linux distributions that have GLIBC >= 2.31 and GLIBCXX >= 3.4.29, but no promises. If there are errors, you will need to compile everything yourself (though I'm happy to do my best to help with that if need be).
In addition to command line programs, we also provide wrappers for our code that allow them to be used with python once the relevant libraries are compiled. This eases the need to save output from the executables to disk and then read them from disk; we directly copy from managed memory to a numpy array once magnification maps and other objects are created.
If you just want the python capabilities (as I suspect is the case for most people currently) and do not wish to use the executables or contribute to the code, then instead of cloning this repository you can pip install microlensing (PyPI page located here). The python package includes precompiled libraries as mentioned above, which may or may not work for you. We hope to expand to cover more architectures in the future. If the included libraries do not work, you will have to clone this repository, compile them yourself, and do a local pip install instead.
The examples directory contains very brief examples of the python packages I've written to create microlensing magnification maps, calculate critical curves and caustics, and calculate number of caustic crossings maps. There are additional examples showing how to generate lightcurves, and a note on units for the magnification maps. The view_output.ipynb example shows how to read the output of the IPM executable.