genulens

genulens ("generate microlensing") simulates microlensing events with the Galactic model of Koshimoto, Baba & Bennett (2021), ApJ, 917, 78. The model is optimized for bulge sightlines and is most appropriate around |l| < 10 deg and |b| < 7 deg.

The v2 alpha release keeps the historical command-line simulator and adds a refactored C++ core, direct Python bindings, source-forward isochrone workflows, genstars-style extinction-map support, custom Python likelihoods, and optical-depth/event-rate summary APIs.

For the full guide, start from docs/. GitHub displays docs/README.md automatically when opening that directory.

Install From PyPI

The Python package is available on PyPI:

pip install genulens

Binary wheels are currently published for Linux x86_64 and macOS arm64. These wheels include the compiled extension, the genulens command-line executable, bundled input tables, and the GSL shared libraries needed by the extension.

Other platforms, including macOS x86_64 and Windows, may fall back to a source build. Source builds require a system GSL installation.

Build From Source

Source builds include:

pip install --no-binary genulens genulens
pip install git+https://github.com/nkoshimoto/genulens.git

To build from a checkout, genulens requires a C++ compiler, CMake, and GSL.

Check that GSL is visible:

gsl-config --libs

Clone and build:

git clone https://github.com/nkoshimoto/genulens.git
cd genulens
make

If GSL is installed in a non-standard prefix:

GSL_ROOT=/path/to/gsl make

The same GSL shared libraries must be visible at runtime. On Linux with a non-standard GSL prefix, set for example:

export LD_LIBRARY_PATH=/path/to/gsl/lib:$LD_LIBRARY_PATH

Build the Python extension:

make python
PYTHONPATH=build python -c "import genulens; print(genulens.__file__)"

The Python extension can also be built from the checkout with:

pip install .

For a non-standard GSL prefix, pass GSL_ROOT to pip:

GSL_ROOT=/path/to/gsl pip install .

For source installs from a non-standard GSL prefix, the built extension records the linked GSL path in its install RPATH. If your platform strips or ignores that RPATH, set LD_LIBRARY_PATH or the platform equivalent at runtime.

Editable installs are supported in environments with scikit-build-core and pybind11:

pip install -e .

Other build targets:

make pre_gapmoe
make test
make clean

CLI and Python

The installed command-line simulator remains available as:

genulens

From a source-tree build, use ./genulens or build/genulens.

The Python API calls the same C++ simulation core directly. It does not run ./genulens as a subprocess and does not parse CLI stdout.

import pandas as pd
import genulens

cfg = genulens.Config(l=1.0, b=-3.9, n_simu=20_000, seed=42)
result = genulens.simulate(cfg)
df = pd.DataFrame(result.to_numpy(), columns=result.columns)

See docs/quickstart.md and docs/python_api.md for details.

The pre_gapmoe histogram helpers are also available from Python when installed from a wheel or source build:

import genulens

rho = genulens.pre_gapmoe.rho_profile(l=1.0, b=-3.9, SOURCE=1)
rho_array = rho.to_numpy()

See docs/pre_gapmoe.md for the helper API and CLI options.

Documentation

• Documentation index
• Quick start
• Python API
• Source-forward mode
• Extinction
• Optical-depth and event-rate maps
• Isochrone systematics
• Architecture notes
• pre_gapmoe helper tools

Notebook examples:

• examples/python_binding.ipynb
• examples/source_isochrone_systematics.ipynb
• examples/rate_summary_map.ipynb

The original command-line usage guide remains available as Usage.pdf.

Citation

Please cite Koshimoto, Baba & Bennett (2021) and Koshimoto & Ranc (2021), Zenodo.4784948 if you use this code in your research.

A separate star simulator, genstars, is also available.

The copyright of the included supplementary code option.cpp belongs to Ian A. Bond and Takahiro Sumi.

Release History

• v2.0.0 alpha 3: Python API for bundled pre_gapmoe helper tables.
• v2.0.0 alpha: PyPI package, refactored C++ core, direct Python API, source-forward isochrone support, extinction-map support, custom Python likelihoods, and rate-summary APIs.
• v1.2, June-July 2022: importance sampling, NSD component, updated Galactic Center position, revised usage documentation, and related genstars release.
• v1.1, June 2021: switched to the GSL random number generator.
• v1.0, May 2021: initial public release.