Models API Reference

This page provides detailed API documentation for the microlensing models in GCMicrolensing.

Single Lens Models

High level models for simulating microlensing events.

This module provides simple classes for single-, double-, and triple-lens microlensing scenarios. The focus is on producing light curves, centroid shifts and animated visualisations for teaching or exploratory analyses.

The implementations rely heavily on the VBMicrolensing and TripleLensing packages for the low level calculations of image positions and magnifications.

class GCMicrolensing.models.OneL1S(t0, tE, rho, u0_list)[source]

Bases: object

Simple single-lens single-source (1L1S) model.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source size in units of the Einstein radius.

  • u0_list (list of float) – Impact parameters to evaluate.

Examples

>>> model = OneL1S(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1])
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list)[source]
plot_light_curve_on_ax(ax)[source]

Plot magnification curve on an existing axis.

Parameters:

ax (matplotlib.axes.Axes) – Axis instance to plot on.

plot_centroid_shift_on_ax(ax)[source]

Plot centroid shift versus time on ax.

Parameters:

ax (matplotlib.axes.Axes) – Axis to draw the centroid shift curve on.

plot_light_curve()[source]

Display the light curve in a new figure.

plot_centroid_shift()[source]

Display the centroid shift curve in a new figure.

animate()[source]

Return a HTML animation of the event.

show_all()[source]

Return an animation with light curve and centroid shift.

_create_animation(figsize=(6, 6), layout='single')[source]

Construct an animation of the microlensing event.

Parameters:

  • figsize (tuple of float, optional) – Size of the matplotlib figure in inches. Defaults to (6, 6).

  • layout ({{'single', 'grid'}}, optional) – 'grid' will also display the light curve and centroid shift during the animation. Defaults to 'single'.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

class GCMicrolensing.models.TwoLens1S(t0, tE, rho, u0_list, q, s, alpha)[source]

Bases: object

Binary-lens, single-source (2L1S) model.

Examples

>>> model = TwoLens1S(t0=0.0, tE=20.0, rho=0.01,
...                  u0_list=[0.1], q=0.1, s=1.5, alpha=45)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q, s, alpha)[source]

Create a binary-lens system.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in units of the Einstein radius.

  • u0_list (list of float) – Impact parameters of the source trajectory.

  • q (float) – Lens mass ratio m2/m1.

  • s (float) – Separation between the lenses in Einstein radii.

  • alpha (float) – Angle of the source trajectory in degrees.

_prepare_systems()[source]

Precompute source trajectories and magnifications.

plot_caustic_critical_curves()[source]

Plot caustics and critical curves for the binary lens.

plot_light_curve()[source]

Plot the binary-lens light curve.

animate()[source]

Return an animation showing the event evolution.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

plot_centroid_trajectory()[source]

Plot the centroid trajectory for each u0 value.

plot_centroid_shift()[source]

Plot the centroid shift amplitude over time.

show_all()[source]

Display a grid of animations and plots.

class GCMicrolensing.models.ThreeLens1SVBM(t0, tE, rho, u0_list, q2, q3, s12, s23, alpha, psi)[source]

Bases: object

Triple-lens, single-source model using VBMicrolensing.

Examples

>>> model = ThreeLens1SVBM(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1],
...                        q2=0.1, q3=0.1, s12=1.2, s23=1.0,
...                        alpha=45.0, psi=30.0)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q2, q3, s12, s23, alpha, psi)[source]

Initialise the VBMicrolensing triple-lens model.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source size in Einstein radii.

  • u0_list (list of float) – Impact parameters to compute.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s12 (float) – Separation between lens 1 and 2 in Einstein radii.

  • s23 (float) – Separation between lens 2 and 3 in Einstein radii.

  • alpha (float) – Source trajectory angle in degrees.

  • psi (float) – Angle between the second and third lens in degrees.

_prepare_systems()[source]

Assemble source trajectories and magnifications.

_setting_parameters()[source]

Initialise the lens geometry in the VBM solver.

_compute_lens_positions()[source]

Return Cartesian positions of the three lenses.

_calculate_image_positions(xs, ys)[source]

Solve the lens equation for a given source position.

Parameters:

  • xs (float) – Coordinates of the source in units of the Einstein radius.

  • ys (float) – Coordinates of the source in units of the Einstein radius.

Returns:

Complex coordinates of the image positions.

Return type:

list[complex]

_true_solution(z_image, xs, ys, so_leps=1e-10)[source]

Check if z_image solves the lens equation.

Parameters:

  • z_image (complex) – Candidate image coordinate.

  • xs (float) – Source coordinates.

  • ys (float) – Source coordinates.

  • so_leps (float, optional) – Numerical tolerance for the solution test.

Returns:

True if the lens equation is satisfied.

Return type:

bool

plot_caustic_critical_curves()[source]

Visualise caustics and critical curves.

plot_light_curve()[source]

Plot the triple-lens light curve.

plot_different_q3_lc(q3_values, reference_q3=None, colormap='RdPu')[source]

Compare light curves for multiple q3 values.

Parameters:

  • q3_values (sequence of float) – Values of the third mass fraction to compute light curves for.

  • reference_q3 (float, optional) – Value used as a baseline when plotting residuals. If None the first entry of q3_values is used.

  • colormap (str, optional) – Name of a matplotlib colormap for the different curves.

class GCMicrolensing.models.ThreeLens1S(t0, tE, rho, u0_list, q2, q3, s2, s3, alpha_deg, psi_deg, rs, secnum, basenum, num_points)[source]

Bases: object

Triple-lens model using a direct solver.

Examples

>>> model = ThreeLens1S(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1],
...                     q2=0.1, q3=0.1, s2=1.2, s3=1.0,
...                     alpha_deg=45.0, psi_deg=30.0,
...                     rs=0.01, secnum=10, basenum=50, num_points=100)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q2, q3, s2, s3, alpha_deg, psi_deg, rs, secnum, basenum, num_points)[source]

Initialise the direct triple-lens solver.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in Einstein units.

  • u0_list (list of float) – Impact parameters for which to compute trajectories.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s2 (float) – Separation of lens 2 from lens 1 in Einstein radii.

  • s3 (float) – Separation of lens 3 from lens 1 in Einstein radii.

  • alpha_deg (float) – Source trajectory angle in degrees.

  • psi_deg (float) – Orientation angle of the third lens in degrees.

  • rs (float) – Source radius used by the solver.

  • secnum (int) – Number of annuli used in contour integration.

  • basenum (int) – Number of base points used in integration.

  • num_points (int) – Number of time samples for the source trajectory.

get_lens_geometry()[source]

Return mass fractions and lens coordinates.

Returns:

(mlens, zlens) where mlens are the mass fractions and zlens contains the x and y coordinates of each lens.

Return type:

tuple of list

_prepare_systems()[source]

Generate trajectories and centroid shifts for each u0.

plot_caustics_and_critical()[source]

Plot VBM caustics and critical curves.

plot_light_curve()[source]

Plot the light curve computed via VBM.

plot_centroid_trajectory()[source]

Plot centroid trajectories for all sources.

plot_shift_vs_time()[source]

Plot centroid shift amplitude for each source over time.

animate()[source]

Create an animation using the direct solver.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

animate_combined()[source]

Animation overlaying caustics and source motion.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

OneL1S

class GCMicrolensing.models.OneL1S(t0, tE, rho, u0_list)[source]

Bases: object

Simple single-lens single-source (1L1S) model.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source size in units of the Einstein radius.

  • u0_list (list of float) – Impact parameters to evaluate.

Examples

>>> model = OneL1S(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1])
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list)[source]
__init__(t0, tE, rho, u0_list)[source]
plot_light_curve_on_ax(ax)[source]

Plot magnification curve on an existing axis.

Parameters:

ax (matplotlib.axes.Axes) – Axis instance to plot on.

plot_centroid_shift_on_ax(ax)[source]

Plot centroid shift versus time on ax.

Parameters:

ax (matplotlib.axes.Axes) – Axis to draw the centroid shift curve on.

plot_light_curve()[source]

Display the light curve in a new figure.

plot_centroid_shift()[source]

Display the centroid shift curve in a new figure.

animate()[source]

Return a HTML animation of the event.

show_all()[source]

Return an animation with light curve and centroid shift.

_create_animation(figsize=(6, 6), layout='single')[source]

Construct an animation of the microlensing event.

Parameters:

  • figsize (tuple of float, optional) – Size of the matplotlib figure in inches. Defaults to (6, 6).

  • layout ({{'single', 'grid'}}, optional) – 'grid' will also display the light curve and centroid shift during the animation. Defaults to 'single'.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

Binary Lens Models

TwoLens1S

class GCMicrolensing.models.TwoLens1S(t0, tE, rho, u0_list, q, s, alpha)[source]

Bases: object

Binary-lens, single-source (2L1S) model.

Examples

>>> model = TwoLens1S(t0=0.0, tE=20.0, rho=0.01,
...                  u0_list=[0.1], q=0.1, s=1.5, alpha=45)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q, s, alpha)[source]

Create a binary-lens system.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in units of the Einstein radius.

  • u0_list (list of float) – Impact parameters of the source trajectory.

  • q (float) – Lens mass ratio m2/m1.

  • s (float) – Separation between the lenses in Einstein radii.

  • alpha (float) – Angle of the source trajectory in degrees.

__init__(t0, tE, rho, u0_list, q, s, alpha)[source]

Create a binary-lens system.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in units of the Einstein radius.

  • u0_list (list of float) – Impact parameters of the source trajectory.

  • q (float) – Lens mass ratio m2/m1.

  • s (float) – Separation between the lenses in Einstein radii.

  • alpha (float) – Angle of the source trajectory in degrees.

_prepare_systems()[source]

Precompute source trajectories and magnifications.

plot_caustic_critical_curves()[source]

Plot caustics and critical curves for the binary lens.

plot_light_curve()[source]

Plot the binary-lens light curve.

animate()[source]

Return an animation showing the event evolution.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

plot_centroid_trajectory()[source]

Plot the centroid trajectory for each u0 value.

plot_centroid_shift()[source]

Plot the centroid shift amplitude over time.

show_all()[source]

Display a grid of animations and plots.

Triple Lens Models

ThreeLens1SVBM

class GCMicrolensing.models.ThreeLens1SVBM(t0, tE, rho, u0_list, q2, q3, s12, s23, alpha, psi)[source]

Bases: object

Triple-lens, single-source model using VBMicrolensing.

Examples

>>> model = ThreeLens1SVBM(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1],
...                        q2=0.1, q3=0.1, s12=1.2, s23=1.0,
...                        alpha=45.0, psi=30.0)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q2, q3, s12, s23, alpha, psi)[source]

Initialise the VBMicrolensing triple-lens model.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source size in Einstein radii.

  • u0_list (list of float) – Impact parameters to compute.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s12 (float) – Separation between lens 1 and 2 in Einstein radii.

  • s23 (float) – Separation between lens 2 and 3 in Einstein radii.

  • alpha (float) – Source trajectory angle in degrees.

  • psi (float) – Angle between the second and third lens in degrees.

__init__(t0, tE, rho, u0_list, q2, q3, s12, s23, alpha, psi)[source]

Initialise the VBMicrolensing triple-lens model.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source size in Einstein radii.

  • u0_list (list of float) – Impact parameters to compute.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s12 (float) – Separation between lens 1 and 2 in Einstein radii.

  • s23 (float) – Separation between lens 2 and 3 in Einstein radii.

  • alpha (float) – Source trajectory angle in degrees.

  • psi (float) – Angle between the second and third lens in degrees.

_prepare_systems()[source]

Assemble source trajectories and magnifications.

_setting_parameters()[source]

Initialise the lens geometry in the VBM solver.

_compute_lens_positions()[source]

Return Cartesian positions of the three lenses.

_calculate_image_positions(xs, ys)[source]

Solve the lens equation for a given source position.

Parameters:

  • xs (float) – Coordinates of the source in units of the Einstein radius.

  • ys (float) – Coordinates of the source in units of the Einstein radius.

Returns:

Complex coordinates of the image positions.

Return type:

list[complex]

_true_solution(z_image, xs, ys, so_leps=1e-10)[source]

Check if z_image solves the lens equation.

Parameters:

  • z_image (complex) – Candidate image coordinate.

  • xs (float) – Source coordinates.

  • ys (float) – Source coordinates.

  • so_leps (float, optional) – Numerical tolerance for the solution test.

Returns:

True if the lens equation is satisfied.

Return type:

bool

plot_caustic_critical_curves()[source]

Visualise caustics and critical curves.

plot_light_curve()[source]

Plot the triple-lens light curve.

plot_different_q3_lc(q3_values, reference_q3=None, colormap='RdPu')[source]

Compare light curves for multiple q3 values.

Parameters:

  • q3_values (sequence of float) – Values of the third mass fraction to compute light curves for.

  • reference_q3 (float, optional) – Value used as a baseline when plotting residuals. If None the first entry of q3_values is used.

  • colormap (str, optional) – Name of a matplotlib colormap for the different curves.

ThreeLens1S

class GCMicrolensing.models.ThreeLens1S(t0, tE, rho, u0_list, q2, q3, s2, s3, alpha_deg, psi_deg, rs, secnum, basenum, num_points)[source]

Bases: object

Triple-lens model using a direct solver.

Examples

>>> model = ThreeLens1S(t0=0.0, tE=20.0, rho=0.01, u0_list=[0.1],
...                     q2=0.1, q3=0.1, s2=1.2, s3=1.0,
...                     alpha_deg=45.0, psi_deg=30.0,
...                     rs=0.01, secnum=10, basenum=50, num_points=100)
>>> model.plot_light_curve()
__init__(t0, tE, rho, u0_list, q2, q3, s2, s3, alpha_deg, psi_deg, rs, secnum, basenum, num_points)[source]

Initialise the direct triple-lens solver.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in Einstein units.

  • u0_list (list of float) – Impact parameters for which to compute trajectories.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s2 (float) – Separation of lens 2 from lens 1 in Einstein radii.

  • s3 (float) – Separation of lens 3 from lens 1 in Einstein radii.

  • alpha_deg (float) – Source trajectory angle in degrees.

  • psi_deg (float) – Orientation angle of the third lens in degrees.

  • rs (float) – Source radius used by the solver.

  • secnum (int) – Number of annuli used in contour integration.

  • basenum (int) – Number of base points used in integration.

  • num_points (int) – Number of time samples for the source trajectory.

__init__(t0, tE, rho, u0_list, q2, q3, s2, s3, alpha_deg, psi_deg, rs, secnum, basenum, num_points)[source]

Initialise the direct triple-lens solver.

Parameters:

  • t0 (float) – Time of closest approach.

  • tE (float) – Einstein crossing time.

  • rho (float) – Source radius in Einstein units.

  • u0_list (list of float) – Impact parameters for which to compute trajectories.

  • q2 (float) – Mass ratio of lens 2 relative to lens 1.

  • q3 (float) – Mass ratio of lens 3 relative to lens 1.

  • s2 (float) – Separation of lens 2 from lens 1 in Einstein radii.

  • s3 (float) – Separation of lens 3 from lens 1 in Einstein radii.

  • alpha_deg (float) – Source trajectory angle in degrees.

  • psi_deg (float) – Orientation angle of the third lens in degrees.

  • rs (float) – Source radius used by the solver.

  • secnum (int) – Number of annuli used in contour integration.

  • basenum (int) – Number of base points used in integration.

  • num_points (int) – Number of time samples for the source trajectory.

get_lens_geometry()[source]

Return mass fractions and lens coordinates.

Returns:

(mlens, zlens) where mlens are the mass fractions and zlens contains the x and y coordinates of each lens.

Return type:

tuple of list

_prepare_systems()[source]

Generate trajectories and centroid shifts for each u0.

plot_caustics_and_critical()[source]

Plot VBM caustics and critical curves.

plot_light_curve()[source]

Plot the light curve computed via VBM.

plot_centroid_trajectory()[source]

Plot centroid trajectories for all sources.

plot_shift_vs_time()[source]

Plot centroid shift amplitude for each source over time.

animate()[source]

Create an animation using the direct solver.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

animate_combined()[source]

Animation overlaying caustics and source motion.

Returns:

HTML representation of the animation for use in notebooks.

Return type:

IPython.display.HTML

Model Parameters

Common Parameters

All microlensing models share these common parameters:

  • t0 (float): Time of closest approach in days

  • tE (float): Einstein crossing time in days

  • rho (float): Source radius in units of Einstein radius

  • u0_list (array-like): List of impact parameters

Binary Lens Parameters

  • q (float): Mass ratio of the second lens to the first lens

  • s (float): Separation between the two lenses in units of Einstein radius

  • alpha (float): Source trajectory angle in degrees

Triple Lens Parameters

  • q2 (float): Mass ratio of the second lens to the first lens

  • q3 (float): Mass ratio of the third lens to the first lens

  • s12 (float): Separation between first and second lenses

  • s23 (float): Separation between second and third lenses (VBM)

  • s2 (float): Separation between first and second lenses (TripleLensing)

  • s3 (float): Separation between first and third lenses (TripleLensing)

  • alpha (float): Source trajectory angle in degrees

  • psi (float): Angle between lens triangle and source trajectory (VBM)

  • psi_deg (float): Angle between second and third lenses (TripleLensing)

TripleLensing-Specific Parameters

  • rs (float): Source radius for image calculations

  • secnum (int): Number of sectors for image finding

  • basenum (int): Base number for image finding algorithm

  • num_points (int): Number of time points for calculations

Model Methods

All models provide these common methods:

  • plot_light_curve(): Plot light curves for all impact parameters

  • animate(): Create an animation of the microlensing event

  • show_all(): Create a comprehensive view with all plots

Additional methods vary by model:

OneL1S Methods

  • plot_centroid_shift(): Plot astrometric centroid shifts

  • plot_light_curve_on_ax(ax): Plot on provided matplotlib axis

  • plot_centroid_shift_on_ax(ax): Plot centroid shift on provided axis

TwoLens1S Methods

  • plot_caustic_critical_curves(): Plot caustic and critical curves

  • plot_centroid_trajectory(): Plot centroid shift trajectories

  • plot_centroid_shift(): Plot centroid shift magnitude vs time

ThreeLens1SVBM Methods

  • plot_caustic_critical_curves(): Plot caustic and critical curves

  • plot_different_q3_lc(): Plot light curves for different q3 values

ThreeLens1S Methods

  • plot_caustics_and_critical(): Plot caustics using VBMicrolensing

  • plot_centroid_trajectory(): Plot centroid shift trajectories

  • plot_shift_vs_time(): Plot centroid shift magnitude vs time

  • animate_combined(): Combined animation with both backends

  • get_lens_geometry(): Get lens geometry parameters

Mathematical Background

The models implement the gravitational lens equation:

\[\vec{\beta} = \vec{\theta} - \vec{\alpha}(\vec{\theta})\]

where: * \(\vec{\beta}\) is the source position * \(\vec{\theta}\) is the image position * \(\vec{\alpha}\) is the deflection angle

For multiple lenses, the deflection angle is the sum of individual lens contributions:

\[\vec{\alpha}(\vec{\theta}) = \sum_i \frac{m_i (\vec{\theta} - \vec{\theta}_i)}{|\vec{\theta} - \vec{\theta}_i|^2}\]

where \(m_i\) and \(\vec{\theta}_i\) are the mass and position of the i-th lens.