genulens 2.0.0a2

Microlensing event simulation with a refactored C++ core and Python API

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 branch 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.

Installation

Released Linux x86_64 and macOS arm64 wheels can be installed with:

pip install genulens

The wheels include the compiled extension, command-line executable, bundled input tables, and the GSL shared libraries needed by the extension. macOS x86_64 may fall back to a source build and therefore requires a system GSL installation.

Source builds, including pip install --no-binary genulens genulens and pip install git+https://github.com/nkoshimoto/genulens.git, require a system GSL installation.

To build from a source 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 source 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 historical CLI remains available:

./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.

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: 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.