.. _physics-gravitationalLensing:

Gravitational Lensing
=====================

Class providing models of the gravitational lensing magnification distribution due to intervening large-scale structure along a line of sight---the probability density and cumulative distribution of the magnification factor :math:`\mu` as a function of source redshift and angular source size. Strong lensing by massive halos can boost observed fluxes significantly, affecting number counts and luminosity functions at the bright end. Implementations typically follow fitting functions calibrated to ray-tracing simulations (e.g.\ :cite:author:`takahashi_full-sky_2017` :cite:year:`takahashi_full-sky_2017`) and depend on the matter power spectrum and cosmological model.

**Default implementation:** ``gravitationalLensingTakahashi2011``

Methods
-------

``magnificationPDF`` → ``double precision``
   Returns the differential probability :math:`\mathrm{d}P/\mathrm{d}\mu` for a source at the given ``redshift`` and angular size ``scaleSource`` to be magnified by factor ``magnification`` due to gravitational lensing.

   * ``double precision, intent(in ) :: magnification, redshift, scaleSource``

``magnificationCDF`` → ``double precision``
   Returns the cumulative probability :math:`P(\mu' \le \mu)` that a source at the given ``redshift`` and angular size ``scaleSource`` has a gravitational lensing magnification less than or equal to ``magnification``.

   * ``double precision, intent(in ) :: magnification, redshift, scaleSource``

.. _physics-gravitationalLensingBaryonicModifier:

``gravitationalLensingBaryonicModifier``
----------------------------------------

A gravitational lensing distribution class which (approximately) modifies another distribution for the effects of baryons. The distribution to modify is specified via the ``[gravitationalLensingBaryonicModifierOriginalDistribution]`` parameter. The modification takes the form:

.. math::

   P(\mu) \rightarrow P(\mu) + \hbox{min}[\alpha,\beta P(\mu)]

where :math:`\alpha=`\ ``[gravitationalLensingBaryonicModifierAlpha]`` and :math:`\beta=`\ ``[gravitationalLensingBaryonicModifierBeta]``. The distribution is then renormalized to ensure that the cumulative probability reaches unity for infinite magnification. As an example, values of :math:`\alpha=2.05\times 10^{-3}` and :math:`\beta=0.62` approximately reproduce the results of :cite:t:`hilbert_strong-lensing_2008`.

**Methods**

* ``renormalize`` — Renormalize the gravitational lensing magnification distribution function.

**Parameters**

* ``[alpha]`` (default ``0.0d0``) — Parameter :math:`\alpha` in the modified gravitational lensing :term:`PDF`, :math:`P(\mu) \rightarrow P(\mu) + \hbox{min}[\alpha,\beta P(\mu)]`.
* ``[beta]`` (default ``0.0d0``) — Parameter :math:`\beta` in the modified gravitational lensing :term:`PDF`, :math:`P(\mu) \rightarrow P(\mu) + \hbox{min}[\alpha,\beta P(\mu)]`.

.. _physics-gravitationalLensingNull:

``gravitationalLensingNull``
----------------------------

A gravitational lensing class that returns a delta-function magnification distribution peaked at :math:`\mu=1` (i.e., no lensing), used as a null model to disable lensing corrections in luminosity or flux calculations.

**Parameters**

* ``[dimensionless]`` (default ``.true.``) — If true the null profile is considered to be dimensionless.

.. _physics-gravitationalLensingTakahashi2011:

``gravitationalLensingTakahashi2011``
-------------------------------------

A gravitational lensing distribution class utilizing the fitting functions of :cite:t:`takahashi_probability_2011` to compute the effects of gravitational lensing. Specifically, eqn. 11 of :cite:t:`takahashi_probability_2011` is used. The parameters :math:`\kappa_\mathrm{empty}` and :math:`\langle \kappa^2 \rangle` are computed from the assumed cosmology and non-linear power spectrum as described by :cite:t:`takahashi_probability_2011`. The parameters, :math:`N_\kappa`, :math:`A_\kappa`, and :math:`\omega_\kappa` of the lensing convergence distribution are determined using the conditions given by :cite:t:`takahashi_probability_2011`.

**(Default implementation)**

**Methods**

* ``lensingDistributionConstruct`` — Construct the gravitational lensing distribution functions for the specified redshift and source scale.
* ``convergenceDistribution`` — Returns the gravitational lensing convergence probability density function at the given convergence.