[Back to **Binary lenses**](BinaryLenses.md)


# Multiple Lenses

The multiple lens equation reads

$$ \vec{y} = \vec{x} - \sum_{k=1}^N m_k \frac{\vec{x}- \vec{x}_k}{|\vec{x}- \vec{x}_k|^2} $$

Here $N$ is the number of lenses, $\vec{x}_k$ is the position of the k-th lens in the lens plane, $\vec{y}$ is the source position and $m_k$ is the mass of the k-th lens. All angular coordinates are in units of the Einstein radius for a unitary mass. 

## Setting the configuration of the lenses

In VBMicrolensing, before using any functions for multiple lenses, the first step is to initialize the lens configuration using the `SetLensGeometry` function. The `SetLensGeometry` function takes just a list of $3N$ values. For each of the $N$ lenses, we need to specify its position in the lens plane and its mass.

```
VBMicrolensing VBM;

int nn=4; // Number of lenses

double pr[] = {     //parameters
    0.0, 0.0, 1.0,    // First lens: x1_1, x1_2, m1
    1.0, -0.7, 1e-4,  // Second lens: x2_2, x2_2, m2
    2.0, 0.7, 1e-4,   // Third lens: x3_1, x3_2, m3
    0.6, -0.6, 1e-6   // Fourth lens: x4_1, x4_2, m4
};

VBM.SetLensGeometry(nn,pr); //Initialize the lens configuration

```

Once the configuration is specified, we can make all calculations we want with the same configuration. If we want to change the lenses configuration, we need to call `SetLensGeometry` again.

Note that we do not impose that the total mass be 1. We remind that the coordinates are in units of the Einstein radius for a unitary mass.

## Multiple lensing with point sources

For point sources, we can calculate the magnification with the `MultiMag0` function. This depends on the source position $y_1$, $y_2$. Here is an example:

```
VBMicrolensing VBM;

int nn=4; // Number of lenses

double pr[] = {     //parameters
    0.0, 0.0, 1.0,    // First lens: x1_1, x1_2, m1
    1.0, -0.7, 1e-4,  // Second lens: x2_2, x2_2, m2
    2.0, 0.7, 1e-4,   // Third lens: x3_re, x3_im, m3
    0.6, -0.6, 1e-6   // Fourth lens: x4_re, x4_im, m4
};

VBM.SetLensGeometry(nn,pr); //Initialize the lens configuration

double y1 = 0.1; //Source position
double y2 = -0.5;

double Mag = VBM.MultiMag0(y1,y2);
printf("Magnification of a point-source = %f", Mag); //Output should be 2.14....
```

## Multiple lensing with extended sources

For extended sources, our recommended function is `MultiMag2`. This function also takes $\rho$ as an argument, the source radius in units of the Einstein angle:

```
VBMicrolensing VBM;

int nn=4; // Number of lenses

double pr[] = {     //parameters
    0.0, 0.0, 1.0,    // First lens: x1_1, x1_2, m1
    1.0, -0.7, 1e-4,  // Second lens: x2_2, x2_2, m2
    2.0, 0.7, 1e-4,   // Third lens: x3_re, x3_im, m3
    0.6, -0.6, 1e-6   // Fourth lens: x4_re, x4_im, m4
};

VBM.SetLensGeometry(nn,pr); //Initialize the lens configuration

double y1 = 0.; //Source position
double y2 = -0.2;
double rho = 0.01; //source radius

double Mag = VBM.MultiMag2(y1,y2, rho);
printf("Multiple Lens Magnification = %f", Mag); //Output should be 5.07...
```

## Three different algorithms

VBMicrolensing offers three different algorithms for multiple lenses calculations. The preferred algorithm can be selected with the `SetMethod` function:
```
VBM.SetMethod(VBMicrolensing::Method::Nopoly); //Choose the method: Nopoly, Multipoly, Singlepoly
```

The three different alternative methods are available as `Method::Singlepoly`, `Method::Multipoly` and `Method::Nopoly`.

`Method::Singlepoly` solves the lens equation with the classical associated complex polynomial. It suffers from numerical errors, making it inaccurate even with configurations involving three lenses when two lenses are small. It is offered here just as a reference, but it is not intended to be used in any scientific calculations.

`Method::Multipoly` still uses associated complex polynomials but, in order to avoid numerical problems, the reference frame is re-centered on each of the lenses for the calculation of the corresponding images. The computational time is longer, but this is a much safer algorithm. Problems come back only with 5 lenses or more.

`Method::Nopoly` uses a Newton-Raphson method on the lens equation without any manipulations. Nopoly is slower than Multipoly for 3 lenses but is faster with 4 or more lenses, where it proves to be the most reliable and accurate method. This is the default method if the user makes no choice.

The full details of all algorithms are described in [V. Bozza, v. Saggese, G. Covone, P. Rota & J. Zhang, A&A 694 (2025) 219](https://ui.adsabs.harvard.edu/abs/2025A%26A...694A.219B/abstract).



## Work in progress

In the current version, some functionalities developed for single and binary lenses are not yet available. These include:

- Astrometry
- Orbital motion
- Binary sources and xallarap

We are working to make these features available as soon as possible.

[Go to **Critical curves and caustics**](CriticalCurvesAndCaustics.md)
