Using BAGLE Models

Overview of bagle.model

The bagle.model module contains a collection of classes and functions that allow the user to construct microlensing models. The available classes for instantiating a microlensing event are shown in the list below. See the API documentation for each class for details.

Example: A Microlens Model Event

To instantiate a model:

from bagle import model

mL = 10.0     # msun
t0 = 57000.00 # MJD
xS0 = np.array([0.000, 0.000])  # arcsec
beta = 1.4  # mas
muS = np.array([8.0, 0.0])   # mas/yr
muL = np.array([0.00, 0.00]) # mas/yr
dL = 4000.0 # pc
dS = 8000.0 # pc
b_sff = [1.0]    # one for each filter
mag_src = [19.0] # one for each filter

event1 = model.PSPL_PhotAstrom_noPar_Param1(mL,
                       t0, beta, dL, dL / dS,
                       xS0[0], xS0[1], muL[0], muL[1],
                       muS[0], muS[1],
                       b_sff, mag_src)

# Get time range for event
t = np.arange(event1.t0 - 3000,
              event1.t0 + 3000, 1)
dt = t - event1.t0

# Quantities you can print
A = event1.get_amplification(t, filt_idx=filt_idx)
shift = event1.get_centroid_shift(t)
shift_amp = np.linalg.norm(shift, axis=1)

List of Available Models

Note, each model class has a name that typically has a structure of

<ModelDataType>_<Parallax>_<GP>_<Parameterization>

For example, PSPL_Phot_noPar_Param2 has a data and model class type of PSPL_Phot, which contains a point-source, point-lens event with photometry only. The model has no parallax, no Guassian Process noise and uses parameterization #2.

The complete list of instantiable model classes is below.

Point source, point lens, photometry only:

Point source, point lens, photometry and astrometry:

Point source, point lens, astrometry only

Point source, binary lens, photometry only

Point source, binary lens, photometry and astrometry

Binary source, point lens, photometry and only

Binary source, point lens, photometry and astrometry

Binary source, binary lens, photometry and astrometry

Finite source, point lens, photometry and astrometry

Finite source, point lens, photometry only

For Developers

Each model class is built up from a menu of different features by inheriting from multiple base classes, each from a different ‘family’ of related classes.

Each microlensing model must contain:

  1. A class from the Data Class Family:

    • PSPL – base class for all Data classes:

      • PSPL_Phot

      • PSPL_PhotAstrom

      • PSPL_GP_Phot

      • PSPL_GP_PhotAstrom

  2. A class from the Parallax Class Family:

    • ParallaxClassABC – base class for all Parallax classes:

      • PSPL_noParallax

      • PSPL_Parallax

      • PSPL_Parallax_RefFrame - adds and additional parameter pi_ref_frame

  3. A class from the GP Class Family: (optional)

    • PSPL_GP – base class for all GP classes.

  4. A class from the Parametrization Class Family:

    • PSPL_Param – base class for all Param classes

      • PSPL_PhotParam1

      • PSPL_PhotParam2

      • PSPL_PhotAstromParam1

      • PSPL_PhotAstromParam2

      • PSPL_PhotAstromParam3

      • PSPL_PhotAstromParam4

      • PSPL_PhotAstromParam5

      • PSPL_GP_PhotParam1

      • PSPL_GP_PhotParam2

      • PSPL_GP_PhotAstromParam1

      • PSPL_GP_PhotAstromParam2

      • PSPL_GP_PhotAstromParam3

      • PSPL_GP_PhotAstromParam4

There is a similar hierarchy for PSBL, etc. Parallax_RefFrame has only been implemented in select PSPL classes, but the framework may easily added to other classes as needed.

For example, the PSPL_PhotAstrom_noPar_Param1 model is declared as:

class PSPL_PhotAstrom_noPar_Param1(ModelClassABC, PSPL_PhotAstrom, PSPL_noParallax, PSPL_PhotAstromParam1)

Class Families

Model Class Family

These are the classes that can be instantiated by the user. The base class is ModelClassABC.

Data Class Family

These classes inform the model of what type of data will be used by the model. If the model will be for photometry only, then a model with the PSPL_Phot class must be selected. These models have the words Phot in their names. If the model will be using photometry and astrometry data, then a model with the PSPL_PhotAstrom must be selected. These models have the words PhotAstrom in their names.

Data containing astrometry will generate a warning that astrometry data will not be used in the model when run through a model using PSPL_Phot. Data that does not contain astrometry run through a model using PSPL_PhotAstrom will generate a RuntimeError.

The base class is PSPL.

Parallax Class Family

These classes set whether the model uses parallax when calculating photometry, calculating astrometry, and fitting data. There are only two options for this class family, PSPL_noParallax and PSPL_Parallax. Models that do not have parallax have the words noPar in their names, while models that do contain parallax have the words Par in their names.

The base class is ParallaxClassABC.

Parameterization Class Family

These classes determine which physical parameters define the model. There are numerous supported parameterizations, including some that only use photometry (Phot), only use astrometry (Astrom), or both (PhotAstrom). A most common developer task would be to make a new parameterization. This entails making a class that inherits from the base class, PSPL_Param (or another subclass), and implements the __init__() function to take in the new parameters and convert them into the BAGLE expected set of parameters (which are usually physical paraemteres in the Solar System Barycentric reference frame).

Some examples of the parameters for different parameterization are:
PhotParam1 :

Point source point lens model for microlensing photometry only. This model includes the relative proper motion between the lens and the source. Parameters are reduced with the use of piRel

Parameters:
t0, u0_amp, tE,
piE_E, piE_N,
b_sff, mag_src,
(ra, dec)
PhotAstromParam1 :

Point Source Point Lens model for microlensing. This model includes proper motions of both the lens and source.

Parameters:
mL, t0, beta,
dL, dL_dS,
xS0_E, xS0_N,
muL_E, muL_N,
muS_E, muS_N,
b_sff, mag_src,
(ra, dec)
PhotAstromParam2 :

Point Source Point Lens model for microlensing. This model includes proper motions of the source and the source position on the sky.

Parameters:
t0, u0_amp, tE, thetaE, piS,
piE_E, piE_N,
xS0_E, xS0_N,
muS_E, muS_N,
b_sff, mag_src,
(ra, dec)
PhotAstromParam3 :

Point Source Point Lens model for microlensing. This model includes proper motions of the source and the source position on the sky. Note it fits the baseline magnitude rather than the unmagnified source brightness.

Parameters:
t0, u0_amp, tE, log10_thetaE, piS,
piE_E, piE_N,
xS0_E, xS0_N,
muS_E, muS_N,
b_sff, mag_base,
(ra, dec)

(ra, dec) are only required if the model is created with a parallax class. More details about each parameterization can be found in the Parameterization Class docstring.

Making a New Model

Each model is, as described above, constructed by combining inheriting from different parent classes that contain the desired features for the model. Each model must have one class from each class family. In addition to this, there are several rules that must be followed when creating a new class.

  1. The data class must match the parameterization class. For example, if the chosen data class is PSPL_Phot, then the parameter class must be PSPL_PhotParam1 (or a different PhotParam in a future version). If the data class is PSPL_PhotAstrom, then the parameter class must be one of the classes with a PhotAstromParam.

  2. Models are built using python’s multiple inheritance feature. Therefore the order in which the parent classes are listed in the model class’ definition matters. Parent classes to models should always be listed in the order:

    1. ModelClassABC

    2. Data Class

    3. Parallax Class

    4. Parameterization Class

    If using the optional GP class, then the order is

    1. ModelClassABC

    2. GP Class

    3. Data Class

    4. Parallax Class

    5. Parameterization Class

  3. Each class must be given the @inheritdocstring decorator, and include the following commands in the model’s __init__:

    • a.super().__init__(*args, **kwargs)

    • startbases(self)

    • checkconflicts(self)

    Each of these performs the following function:

    • super().__init__(*args, **kwargs): Inherits the __init__ from the Parameterization Class.

    • startbases(self): Runs a start command on each parent class, giving each parent class a chance to run a set of functions upon instantiation.

    • checkconflicts(self): Checks to confirm that the combination of parent classes in the model are valid.

  4. Models should be named to reflect the parents classes used to construct it, as outlined in the above sections.

Other notes

All times must be reported in MJD in the Solar System Barycentric reference frame (TODO: CONFIRM and EXPAND!).

For a more detailed explanation of how BAGLE models are structured and how you can add your own new models and parameterizations, see Making Your Own Microlens Models.