This is a collection of software creating simulated galaxy-galaxy lenses as a function of time. This includes both images and light curves. In a nutshell, MOLET can:
- simulate galaxy-galaxy lens images,
- calculate corresponding light curves (magnification and time-delay),
- include microlensing self-consistently,
- provide 'observed' light curves in any band, with given observing strategy.
Here is a "TLDR" to get you started:
- Get an account at https://gerlumph.amnh.org
- Add your credentials to a copy of the .env_example file.
- Create a directory to hold magnification maps and another one to hold your MOLET simulations.
- Run the docker command specifying the location of your .env file and these two directories.
- You are ready to run MOLET within the docker container, e.g.:
./molet_driver tests/quasar/test_A/molet_input.json
A detailed demonstration and application of MOLET's capabilities can be found in Vernardos (2022).
Here is a list of papers using MOLET:
- "LTDE: The Lens Time Delay Experiment I. From pixels to light curves" - Neira, et al. 2026
- "Exploiting the diversity of modeling methods to probe systematic biases in strong lensing analyses" - Galan et al. 2024
- "Measuring the substructure mass power spectrum of 23 SLACS strong galaxy-galaxy lenses with convolutional neural networks" - Fagin et al. 2024
- "Modeling lens potentials with continuous neural fields in galaxy-scale strong lenses" - Biggio et al. 2023
- "COOLEST: COde-independent Organized LEns STandard" - Galan et al. 2023
- " Using wavelets to capture deviations from smoothness in galaxy-scale strong lenses" - Galan et al. 2022
- "The Very Knotty Lenser: Exploring the role of regularization in source and potential reconstructions using Gaussian process regression" - Vernardos & Koopmans 2022
- "Time-delay estimation in unresolved lensed quasars" - Biggio et al. 2022
MOLET has the unique capability of including microlensing in the simulated lensed light curves of a variable background source, like a quasar or supernova. In order to achieve this, several microlensing magnification maps are required that need to be generated by software that is not included as part of MOLET. The user needs to store such maps somewhere in their system and provide the full path of their location to MOLET, referred to as /path/to/gerlumph/maps/ in the following.
The GERLUMPH project (see Vernardos & Fluke 2014, Vernardos et al. 2014, and Vernardos et al. 2015) has produced more than 70,000 microlensing magnification maps that are readily available through a publicly accessible database and API. MOLET calculates the required map parameters and fetches the corresponding maps automatically. To gain access to the GERLUMPH API the user needs to:
- Register for an account at: https://gerlumph.amnh.org
- Create a .env file containing the API URLs and the user credentials.
- Make this file accessible at the root directory of the MOLET installation (see section on "Installing" below).
MOLET will automatically determine which GERLUMPH maps are needed, download them at the specified /path/to/gerlumph/maps/, and use them in microlensing simulations, without any other intervention by the user.
If the required maps do not exist in the GERLUMPH database, or if the user wants to make use of their own custom maps, locally stored maps can be used with MOLET. The following procedure should be used:
- Know the κ (convergece), γ (shear), s (smooth matter fraction), width (in units of the Einstein radius), and resolution (in pixels). Optionally, know the number of microlenses used, the total computational time, the average magnification and average number of rays shot per pixel (depends on the method used to generate the map).
- Come up with a unique map ID, and insert it together with the above fields as a new line in the data/gerlumph.db file.
- Set $api_status in molet_driver to false.
Re-running MOLET will now use a local table, stored in data/gerlumph.db, to match the κ, γ, and s of the lensed point-source images to magnification maps, where the local/custom maps would appear.
Warning
The actual maps will need to be stored in a sub-directory of /path/to/gerlumph/maps/ named with the map ID. The user needs to make sure that the map data are stored in the same format as GERLUMPH and with these specific file names:
- map.bin: a binary file holding ray-counts per pixel stored as 4-byte integers
- mapmeta.dat: a text file with the specific structure (signle-spaced):
<average magnification> <average number of rays per pixel>
<resolution>
<width>
<kappa> <gamma> <s>
There are two different ways to setup a working installation of MOLET: through a docker container or a local installation. The quickest is using the provided docker containers, however, such virtualization makes the computations significantly slower. This approach is recommended for familiarizing oneself with the code, test runs, and even some development. Setting up a local installation is a bit more time consuming, but the code can run considerably faster in this way. This is the recommended approach for using MOLET in production mode, e.g. when one needs to simulate more than a handful of systems.
The following timing results illustrate the speed of a local installation compared to a docker container. Enabling GPU support can dramatically increase the speed of microlensing related computations. The two timing tests - "Test 2" that includes microlensing calculated on-the-fly and "Test 5" that generates just a simulated image of a lens) can be found in the tests/ directory. On a DELL Precision laptop with an NVIDIA GPU:
| docker CPU | local CPU | local GPU | |
|---|---|---|---|
| Test 2: | 120s | 80s (x1.5 faster) | 22s (x5.5 faster) |
| Test 5: | 8.8s | 1.8s (x5 faster) | no use of GPUs |
Docker containers provide a pre-compilled environment to run MOLET with all required third-party software and libraries installed. These include general purpose software and the lensing-specific gerlumphpp and vkl_lib. After installing docker on your system through a package manager, type:
docker pull gvernard/molet:production
docker run --network host -it --rm \
-v </absolute/path/to/gerlumph/maps/>:/home/gerlumph_maps:rw \
-v </absolute/path/to/.env/file>:/home/molet/.env:ro \
-v </absolute/path/to/results/>:/home/molet_output/:rw \
gvernard/molet:production
which pulls the production docker image of MOLET and runs a container with mounted external volumes (the docker container is basically a virtual machine completely isolated from the user's system, unless such read-and-write or read-only volumes are mounted, see here for more details).
There are three mounted volumes in the above command that should exist in the user's system already:
- The path </absolute/path/to/gerlumph/maps/> should contain the GERLUMPH maps and be structured as described above (mounted as a read-and-write volume).
- The file </absolute/path/to/.env/file/> must contain the GERLUMPH API URLs and user credentials in order to allow for seamless magnification map downloads (mounted as read-only).
- The path </absolute/path/to/results/> should hold all the user input and output files for persistent storage after quiting the docker container (mounted as read-and-write).
For development of MOLET code, e.g. adding extra functionality or tweaks, a different docker container is available with all the tools required to re-compile the code.
Simply replace gvernard/molet:production with gvernard/molet:development in the above docker command.
The commands to re-compile the code are make; make install.
If additional third-party libraries are required then it is strongly advised to use a local installation, as described below.
The following software is required in order to proceed with the installation of MOLET:
- CMake
- Autotools (for the "autoreconf" command)
- A C/C++ compiler compatible with the c++17 standard (e.g. GCC version 8 and above)
- A CUDA compiler (i.e. "nvcc") for GPU support.
These programs are standard packages that can be easily installed via package managers.
MOLET uses third party libraries that must be pre-installed in the system. For convenience, a list of commands that download and install all these libraries is provided in the third_party/install_all.sh script.
To use the install_all.sh script, the user needs to provide three command line arguments:
- -g: either "yes" or "no", enables GPU support
- -m: the absolute path to a directory with the GERLUMPH maps (see </absolute/path/to/gerlumph/maps/>)
- -s: the absolute path to a directory anywhere in the user's system where all the third party libraries will eventually be installed.
The first two arguments are relevant only for the microlensing part of the code, but they have to be specified anyway (one can set '-g no' and provide a dummy directory as a path to maps if microlensing is not required). These two arguments can be changed at any time, requiring only the re-compillation of the gerlumph++ library (see its README on how to achieve this).
MOLET will eventually be linked to the libraries installed by this script.
Using different libraries, even if some already exist in the user's system, is a somewhat advanced task, which the users are advised not to undertake unless they are familiar with installing software through autotools (through ./configure; make; make install).
Note
If the installation produces errors, then you can edit the script, e.g. comment out the part that downloads the source files for the libraries, and re-run it to debug.
Once all the third-party libraries have been installed (either by the third_party/install_all.sh script or any other way), the user needs to:
- switch to the root directory of the MOLET installation,
- run
autoreconf -ithat will produce a ./configure script, - execute the
./configurescript, passing it the system path to the installed third-party libraries. In the following example, /path/to/libraries/ should corredpond to the directory the user passed as argument to the install_all.sh script through the '-s' option:
Configure Command
./configure \
--with-jq=/path/to/libraries/jq \
--with-fftw3=/path/to/libraries/fftw \
--with-cfitsio=/path/to/libraries/cfitsio \
--with-CCfits=/path/to/libraries/CCfits \
--with-gmp=/path/to/libraries/gmp \
--with-CGAL=/path/to/libraries/CGAL \
--with-jsconcpp=/path/to/libraries/jsoncpp \
--with-png=/path/to/libraries/libpng \
--with-sqlite3=/path/to/libraries/sqlite3 \
--with-vkl=/path/to/libraries/vkl_lib \
--with-gerlumph=/path/to/libraries/gerlumphpp
- execute
makefollowed bymake install, and - make sure there is a .env file at the MOLET root directory with their GERLUMPH API credentials for direct access to precomputed magnification maps.
MOLET can be run now, and the code can even be recompiled using just make; make install.
The ./configure command needs to be executed only once during installation to link the libraries.
Only if the location of a library changes the user will need to modify the corresponding option to the ./configure script accordingly and follow the same steps from there.
In the root directory of the MOLET installation there is a directory named tests/, where a few standard use cases are given as examples. Inside this directory there is a README file describing the various tests. The user can ensure that MOLET was installed properly by running one or more tests with the command:
./molet_driver tests/quasar/test_A/molet_input.json
The user can move and rename these directories anywhere in their system and use them as a starting point for their own simulations.
A python visualization program is provided that can be used to plot the generated light curves. This program can be executed independently of MOLET (e.g. no need to run it in a docker container), as long as all the required python packages are available (matplotlib, numpy, astropy, etc).
cd plotting/
python plot_light_curves.py </full/path/to/simulation/directory/> mock_<index_in>_<index_ex>/ <instrument_name>
where <instrument_name> depends on the input options of the simulation (see below) and mock_<index_in>_<index_ex> refers to a single lens realization, i.e. it is a MOLET output directory containing two (four) light curves for a double (quad) lens. Here is an example of such a plot:
The main script calling the various programms and managing input and output files is molet_driver.sh. Each simulation is contained in a single directory that needs to include a .json input file, an input_files directory and the eventual output.
A .json file is required with all the relevant parameters. The input_files directory needs to include at least the intrinsic light curves, which are stored as an associative array with two keys, "time" in days and "signal" in aparent magnitudes, each one being a coma-separated list of values. Similarly for an unmicrolensed intrinsic light curve component, if present. If custom microlensing light curves are provided, another .json file needs to be provided in input_files with the same structure as the intrinsic and unmicrolensed light curve files, but having a list of light curves per image (run the tests to see examples, see below).
The output consists of an output directory containing separate images of the static image components and other quantities of interest. One or more mock_<index_in>_<index_ex> directories are also produced, which contain the results for each realization using the provided intrinsic and extrinsic light curves. These directories are named after the corresponding indices in the .json file input lists. The purely microlensing light curves will be located in the output directory. Inside each mock_<index_in>_<index_ex> directory there is a file with the resulting continuous (daily cadence) light curves and another one with those sampled according to the provided time vector. These output files are in the same format as the input light curve .json files. Finally, any requested image cutouts will also be located these directories.
Coming soon
Coming soon
This is an extension of the 'moving source' model, where the source profile that is crossing a magnification map is allowed to vary as well. This is actually implicitly happening in the case of the 'moving source' model through the intrinsic variability of the source: the time-dependent brightness shifts dictated by the intrinsic variability light curve are the same for all the pixels of an otherwise unchanged brightness profile. Here, the source profile is allowed to change in shape, size, features, etc, as it moves through the magnification map.
Input: The user needs to provide a sequence of snapshots of the source per instrument, given as sequentially named, 4-character long .fits files, e.g. 0000.fits, 0001.fits, etc. The brightness needs to be in units of flux, matching the provided instrument specification (through the zero-point magnitude). In addition, the following parameters need to be provided, per instrument:
- time: an array of time values in days in the observer's frame, starting from 0. Its length has to match the number of provided snapshots. The time span must cover at least the period of observations + the maximum time delay of the system.
- Nx,Ny: the number of pixels in the x and y directions. Must be the same (square) for all the brightness profiles.
- pixSize: the pixel size in 1014 cm. Must be the same for all the brightness profiles.
Output: The intrinsic variability curve is calculated by the provided snapshots.
An example is given in test_6.
A few basic examples of instruments (i.e. a psf, some resolution, bandwidth, etc) are provided with MOLET, but the user can easily add their own. From the root installation directory, the user needs to run:
./bin/aux_create_instrument /path/to/instrument/specs.json /path/to/instrument/psf.fits
passing the path to a .json and .fits files that contain the information on the instrument. Examples of such files can be found in data/instrument_data/. The .fits file is just an image of the PSF, but its dimensions (physical and in pixels) need to be provided in the specs.json file.
For the same reason, any instruments installed by the user (see below) will not be saved when the quitting the docker container, and consequently will need to be installed every time (e.g. by running a simple script).